omakit 0.5.1 → 0.6.1

package/tools/marketplace/completion-check.mjs

@@ -23,6 +23,7 @@ import { spawnSync } from "node:child_process"
 import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 import { completionInstall, parseCompletionHeader } from "./completion.mjs"
+import { COMMANDS } from "./usage.mjs"
 import { omakitStateDir } from "./paths.mjs"
 
 /** Milliseconds an interactive shell may take to answer a probe; a hung rc file is reported, not waited for. */
@@ -172,7 +173,24 @@ export function installedCompletion(env = process.env) {
  *
  * @param {{ version: string, pin: string, env?: NodeJS.ProcessEnv }} options
  */
-export function completionStatus({ version, pin, env = process.env }) {
+/** The subcommands of COMMANDS a script text does not name as a word; a script from another surface lacks some. */
+export function subcommandsMissingFrom(text, commands = COMMANDS) {
+  // The names from the signatures alone: subcommandsOf() also lists the
+  // shipped blocks for `add`, which reads blocks/, and doctor may run from
+  // a tree without it (tests copy bin, tools and package.json alone).
+  const names = commands.map((command) => [].concat(command.signature)[0].match(/^omakit +([a-z][a-z-]*)/)?.[1]).filter(Boolean)
+  return names.filter((name) => !new RegExp(`(?<![A-Za-z0-9_-])${name}(?![A-Za-z0-9_-])`).test(text))
+}
+
+function readScript(path) {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    return ""
+  }
+}
+
+export function completionStatus({ version, pin, env = process.env, commands = COMMANDS }) {
   const shell = basename(env.SHELL || "")
   const target = completionInstall(env)
   if (!target) return { state: "info", shell: shell || null, detail: shell ? `no completion script for ${shell}; there is one for bash, zsh and fish` : "$SHELL is not set, so no completion script is installed", action: null, evidence: { shell: shell || null } }
@@ -186,6 +204,14 @@ export function completionStatus({ version, pin, env = process.env }) {
   if (installed.version !== version || installed.pin !== pin) {
     return { state: "advice", shell: target.shell, detail: `${identity}; this omakit is ${version} at pin ${pin.slice(0, 7)}, so the script is stale`, action: "omakit setup", evidence }
   }
+  // The script's content against the current command surface, not its
+  // header alone: measured on 2026-09-19 by a first user whose installed
+  // script named this version and pin and lacked `add` and `lab`, after a
+  // setup that could not replace it (EROFS); doctor called it healthy
+  // (docs/evidence/ux/2026-09-19-first-user-test.json, finding 8).
+  const missing = subcommandsMissingFrom(readScript(target.path), commands)
+  evidence.missingSubcommands = missing
+  if (missing.length) return { state: "advice", shell: target.shell, detail: `${identity}; the script does not complete ${missing.join(", ")}, so it is from another command surface`, action: "omakit setup", evidence }
   if (!probe.ran) return { state: "unknown", shell: target.shell, detail: `${identity}; a new ${target.shell} could not be asked: ${probe.reason}`, action: null, evidence }
   if (!probe.loader) return { state: "advice", shell: target.shell, detail: `${identity}; a new ${target.shell} has no completion loader, so the script is never read`, action: "omakit setup", evidence }
   if (probe.spec === "none") return { state: "advice", shell: target.shell, detail: `${identity}; the loader is there but a new ${target.shell} does not load the script`, action: "omakit setup", evidence }

package/tools/marketplace/completion.mjs

@@ -9,11 +9,16 @@
 // startup plus a pin read is not something to put behind a TAB. The script says
 // in its own header which pin it came from and how to regenerate it.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 import { tagSlug } from "./form.mjs"
 import { COMMANDS, COMPLETION_SHELLS } from "./usage.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
+import { shippedBlocks } from "../blocks/registry.mjs"
+import { suiteNames } from "../lab/suites.mjs"
+
+/** The words after `omakit lab`, for TAB: the actions, and the suites after `run`. */
+export const LAB_ACTIONS = Object.freeze(["prove", "inspect", "setup", "prune"])
 
 /**
  * The completion model, read out of the help data. A subcommand is the word
@@ -41,8 +46,12 @@ export function subcommandsOf(commands = COMMANDS) {
     // `<target>` completes as a directory; `<plugin-id-or-dir>` as the ids
     // the running shell has installed, read at TAB time, with a directory
     // as the fallback.
-    const target = /<plugin-id-or-dir>/.test(signature) ? "plugin" : /<target>/.test(signature) ? "directory" : false
-    return { name, description: sentence, flags, target }
+    // `omakit add <block> [<plugin-dir>]`: the block names omakit ships for
+    // the first word, a directory for the second.
+    // `omakit lab <action> [<suite>]`: the four actions for the first word,
+    // the suites for the second after `prove`.
+    const target = /^omakit +lab\b/.test(signature) ? "lab" : /^omakit +add\b/.test(signature) ? "block" : /<plugin-id-or-dir>/.test(signature) ? "plugin" : /<target>/.test(signature) ? "directory" : false
+    return { name, description: sentence, flags, target, blocks: target === "block" ? shippedBlocks().map((block) => block.name) : [], actions: target === "lab" ? [...LAB_ACTIONS] : [], suites: target === "lab" ? suiteNames() : [] }
   })
 }
 
@@ -171,6 +180,18 @@ function bash({ subcommands, categories, tags, pin, version }) {
       lines.push('      COMPREPLY=($(compgen -W "$(_omakit_plugin_ids)" -- "$cur"))')
       lines.push('      if ((${#COMPREPLY[@]} == 0)); then COMPREPLY=($(compgen -d -- "$cur")); compopt -o filenames 2>/dev/null; fi')
       lines.push("    fi")
+    } else if (sub.target === "block") {
+      lines.push('    if ((COMP_CWORD == 2)); then')
+      lines.push(`      COMPREPLY=($(compgen -W ${single(sub.blocks.join(" "))} -- "$cur"))`)
+      lines.push('    elif ((COMP_CWORD == 3)); then')
+      lines.push('      COMPREPLY=($(compgen -d -- "$cur")); compopt -o filenames 2>/dev/null')
+      lines.push("    fi")
+    } else if (sub.target === "lab") {
+      lines.push('    if ((COMP_CWORD == 2)); then')
+      lines.push(`      COMPREPLY=($(compgen -W ${single(sub.actions.join(" "))} -- "$cur"))`)
+      lines.push('    elif ((COMP_CWORD == 3)) && [[ ${COMP_WORDS[2]} == prove ]]; then')
+      lines.push(`      COMPREPLY=($(compgen -W ${single(sub.suites.join(" "))} -- "$cur"))`)
+      lines.push("    fi")
     } else if (sub.target) {
       lines.push('    COMPREPLY=($(compgen -d -- "$cur"))')
       lines.push("    compopt -o filenames 2>/dev/null")
@@ -239,6 +260,8 @@ function zsh({ subcommands, categories, tags, pin, version }) {
       return single(flag)
     })
     if (sub.target === "plugin") specs.push(single("1:plugin:_omakit_plugins"))
+    else if (sub.target === "block") specs.push(single(`1:block:(${sub.blocks.join(" ")})`), single("2:plugin directory:_directories"))
+    else if (sub.target === "lab") specs.push(single(`1:action:(${sub.actions.join(" ")})`), single(`2:suite:(${sub.suites.join(" ")})`))
     else if (sub.target) specs.push(single("1:target:_directories"))
     if (specs.length) lines.push(`      _arguments ${specs.join(" ")}`)
     lines.push("      ;;")
@@ -281,7 +304,12 @@ function fish({ subcommands, categories, tags, pin, version }) {
   for (const sub of subcommands) {
     const when = `-n ${single(`__fish_seen_subcommand_from ${sub.name}`)}`
     if (sub.target === "plugin") lines.push(`complete -c omakit ${when} -a '(__omakit_plugin_ids)'`)
-    if (sub.target) lines.push(`complete -c omakit ${when} -a '(__fish_complete_directories)'`)
+    if (sub.target === "block") lines.push(`complete -c omakit ${when} -a ${single(sub.blocks.join(" "))}`)
+    if (sub.target === "lab") {
+      lines.push(`complete -c omakit ${when} -n ${single(`not __fish_seen_subcommand_from ${sub.actions.join(" ")}`)} -a ${single(sub.actions.join(" "))}`)
+      lines.push(`complete -c omakit ${when} -n ${single("__fish_seen_subcommand_from prove")} -a ${single(sub.suites.join(" "))}`)
+    }
+    if (sub.target && sub.target !== "lab") lines.push(`complete -c omakit ${when} -a '(__fish_complete_directories)'`)
     for (const { flag, value } of sub.flags) {
       const long = `-l ${flag.slice(2)}`
       if (value === "category") lines.push(`complete -c omakit ${when} ${long} -x -a ${single(categories.map(fishWord).join(" "))}`)

package/tools/marketplace/doctor.mjs

@@ -37,14 +37,18 @@
 // nothing the tool uses.
 
 import { execFileSync } from "node:child_process"
-import { readFileSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
-import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinShape, requirePin } from "./pin.mjs"
 import { LIVE_PATHS } from "./registry.mjs"
-import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
+import { credential, defaultBranchHead, getJson, GitHubError } from "./github.mjs"
 import { compareVersions, NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
+import { sourceCommit } from "../blocks/add.mjs"
+import { recordedCommit } from "../blocks/record-commit.mjs"
 import { pathHint } from "./path-hint.mjs"
 import { completionStatus } from "./completion-check.mjs"
+import { inspectLab } from "../lab/inspect.mjs"
+import { labDoctorChecks } from "../lab/report.mjs"
 
 /** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
 function repositoryPage(repository) {
@@ -62,9 +66,10 @@ export function tool(repoRoot) {
   }
 }
 
-function version(command, args = ["--version"]) {
+/** The first line a command prints for `--version`, or null when it is not there; shared with `setup`. */
+export function version(command, args = ["--version"]) {
   try {
-    return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n")[0]
+    return execFileSync(command, args, { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n")[0]
   } catch {
     return null
   }
@@ -72,7 +77,7 @@ function version(command, args = ["--version"]) {
 
 /** The object id a path has at a commit in the pinned checkout: a tree id for a directory, a blob id for a file. Local; a blob-filtered clone still has every tree. */
 function pinObjectId(pinDir, commit, path) {
-  return execFileSync("git", ["-C", pinDir, "rev-parse", `${commit}:${path}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+  return execFileSync("git", ["-C", pinDir, "rev-parse", `${commit}:${path}`], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
 }
 
 /**
@@ -221,6 +226,21 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     }
   }
 
+  // Where this omakit's code comes from, and whether `add` can name it: a
+  // checkout (git is the source), a package the release step stamped
+  // (tools/blocks/commit.json), or a package packed without that step,
+  // which names no commit and refuses `add`. Measured on 2026-09-19: a
+  // candidate packed with a raw `npm pack` called itself the published
+  // version and nothing said it could not add a block.
+  {
+    const commit = sourceCommit(repoRoot)
+    const checkout = existsSync(join(repoRoot, ".git"))
+    const recorded = recordedCommit(repoRoot)
+    if (checkout && commit) add("omakit.source", "ok", `a checkout at ${commit.slice(0, 7)}; add stamps that commit`, null, { origin: "checkout", commit })
+    else if (commit) add("omakit.source", "ok", `a package the release step stamped with commit ${commit.slice(0, 7)}${recorded ? "" : " (npm's gitHead)"}; add stamps that commit`, null, { origin: "package", commit })
+    else add("omakit.source", "advice", "a package packed without the release step: it names no source commit, so `omakit add` refuses (no-source-commit)", "install an artifact the release step packed (`npm run pack:release` in a checkout, or the registry's release of this version once published)", { origin: "unstamped", commit: null })
+  }
+
   // Reachable as a bare command, or the one line that makes it so for this
   // install (path-hint.mjs). Measured: an npm prefix whose bin is not on PATH
   // installs a command nobody can run, and nothing said so.
@@ -246,15 +266,25 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   const git = version("git")
   add("git", git ? "ok" : "problem", git || "git was not found on PATH", git ? null : "Install git.")
 
+  // The blocks start their supervisor and helper through /usr/bin/python3
+  // by absolute path (blocks/run/Run.qml), never through PATH, so this is
+  // the one path that matters; a stock Omarchy 4.0.3 has it as a
+  // dependency of its desktop packages. Advice, not a problem: nothing
+  // omakit runs here needs it, and a plugin without a block never will.
+  const python = version("/usr/bin/python3")
+  add("blocks.python", python ? "ok" : "advice",
+    python ? `${python} at /usr/bin/python3, where the Run and Store blocks start it` : "/usr/bin/python3 was not found; a plugin's Run block reports python-missing here",
+    python ? null : "Install python (the blocks start /usr/bin/python3 by absolute path).")
+
   const dir = marketplacePinDir(repoRoot)
   let identity = null
   try {
     identity = requirePin(repoRoot).identity
     add("pin.checkout", "ok",
       `${identity.commit} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}) at ${dir}`)
-    const sparse = pinIsSparse(dir)
-    add("pin.size", sparse ? "ok" : "advice", `${pinDiskUsage(dir)}${sparse ? ", sparse" : ", full checkout"}`,
-      sparse ? null : `This checkout predates the sparse fetch and is far larger than it needs to be. Remove ${dir} and run \`omakit pin\` to refetch only what omakit reads.`)
+    const shape = pinShape(dir)
+    add("pin.size", shape.sparse ? "ok" : "advice", `${pinDiskUsage(dir)}${shape.sparse ? ", sparse: the pinned paths and nothing else" : `, a full checkout: ${shape.extra.length} entr${shape.extra.length === 1 ? "y" : "ies"} beyond the pinned paths (${shape.extra.slice(0, 5).join(", ")}${shape.extra.length > 5 ? ", ..." : ""})`}`,
+      shape.sparse ? null : `This checkout carries more than the four paths omakit reads. Remove ${dir} and run \`omakit pin\` to refetch only those.`, { sparse: shape.sparse, extra: shape.extra, sparseCheckoutConfig: shape.sparseCheckoutConfig })
   } catch (error) {
     add("pin.checkout", "problem", error.message, error.remedy || "omakit pin")
   }
@@ -296,6 +326,14 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
         ? "`gh auth login` is enough. omakit reads that login for GET requests only and never copies it anywhere."
         : "Install GitHub's `gh` CLI and run `gh auth login`. omakit reads that login for GET requests only.")
 
+  // The lab: KVM, QEMU, the firmware, gpg, free disk, the verified ISO and
+  // the base, each with its measured reason, every one advice and never a
+  // problem, because the lab is optional and doctor installs nothing.
+  // Read-only: inspectLab creates no directory, verifies nothing online
+  // and starts nothing.
+  phase("reading the lab")
+  for (const check of labDoctorChecks(await inspectLab({ env }))) checks.push(check)
+
   return { checks, problems: checks.filter((check) => check.state === "problem").length }
 }
 

package/tools/marketplace/github.mjs

@@ -109,7 +109,17 @@ export function token() {
 /** The one host the borrowed gh credential may be sent to. */
 export const CREDENTIAL_HOST = "api.github.com"
 
-async function get(url, { accept, signal } = {}) {
+/**
+ * Every request has a deadline. Measured on 2026-09-19 by a first user on
+ * a host whose network dropped packets instead of refusing them: a fetch
+ * with no signal waited on the kernel's own timeout, minutes, and
+ * `npm test` hung with it. A caller's signal wins; without one, the
+ * response has to start within GET_DEADLINE_MS (the body of a large
+ * object, the ISO, streams on past it under its own progress).
+ */
+export const GET_DEADLINE_MS = 20_000
+
+async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
   const { host } = new URL(url)
   // The credential is GitHub's and goes to GitHub's API and nowhere else.
   // Measured before this held: `omakit upgrade` and `doctor` sent the gh
@@ -123,14 +133,18 @@ async function get(url, { accept, signal } = {}) {
   }
   const auth = authenticated ? token() : null
   if (auth) headers.authorization = `Bearer ${auth}`
+  // A resumed download asks for the rest of the object; the lab's ISO
+  // fetch is the one caller, and a server that ignores the range answers
+  // 200 from the start, which the caller handles by starting over.
+  if (rangeFrom > 0) headers.range = `bytes=${rangeFrom}-`
   let response
   try {
-    response = await fetch(url, { method: "GET", headers, redirect: "follow", ...(signal ? { signal } : {}) })
+    response = await fetch(url, { method: "GET", headers, redirect: "follow", signal: signal || AbortSignal.timeout(GET_DEADLINE_MS) })
   } catch (error) {
     // Node reports every transport failure as "fetch failed" with the real
     // reason in `cause`. A person needs the reason, and the CLI keys its
     // remedy on the code, so both are carried out of here.
-    const cause = error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
+    const cause = error?.name === "TimeoutError" ? `no answer within ${GET_DEADLINE_MS / 1000} s` : error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
     const { host, pathname } = new URL(url)
     throw new GitHubError("network-unavailable", `${host} did not answer (${cause}) while reading ${pathname}`)
   }
@@ -158,6 +172,16 @@ export async function getText(url, accept) {
   return (await get(url, { accept })).text()
 }
 
+/**
+ * A streamed GET for a large object, the response itself: the lab reads
+ * `body` chunk by chunk into a file. `rangeFrom` resumes. Same call site,
+ * same literal method, and the credential stays with api.github.com; the
+ * ISO origin (iso.omarchy.org) never sees it.
+ */
+export async function getStream(url, { rangeFrom = 0, signal } = {}) {
+  return get(url, { accept: "application/octet-stream", signal, rangeFrom })
+}
+
 /** Parse a marketplace issue URL into its parts. */
 export function parseIssueUrl(value) {
   const match = String(value || "").trim().match(
@@ -171,9 +195,31 @@ export async function issue(owner, repository, number) {
   return getJson(`https://api.github.com/repos/${owner}/${repository}/issues/${number}`)
 }
 
-/** Resolve the account whose credential gh lent us; never persist it. */
-export async function authenticatedUser() {
-  if (!token()) throw new GitHubError("login-required", "Account-wide watch needs your GitHub login. Run `gh auth login`, or pass --user <login> to read a public account.")
+/** Whether api.github.com answers at all, unauthenticated, within a short deadline; the one probe that tells a missing network from a missing login. */
+export async function githubReachable({ readJson = getJson, timeoutMs = 5000 } = {}) {
+  try {
+    await readJson("https://api.github.com/", { signal: AbortSignal.timeout(timeoutMs) })
+    return { reachable: true, reason: null }
+  } catch (error) {
+    if (error?.code === "network-unavailable") return { reachable: false, reason: error.message }
+    // Any answer at all (a 4xx included) means the network is there.
+    return { reachable: true, reason: null }
+  }
+}
+
+/**
+ * Resolve the account whose credential gh lent us; never persist it. With
+ * no credential, the network is asked first: measured on 2026-09-19 by a
+ * first user without a connection, `watch --list` said `login-required`
+ * and sent them to `gh auth login`, when no login would have helped
+ * (docs/evidence/ux/2026-09-19-first-user-test.json, finding 4).
+ */
+export async function authenticatedUser({ reachable = githubReachable, hasToken = () => Boolean(token()) } = {}) {
+  if (!hasToken()) {
+    const probe = await reachable()
+    if (!probe.reachable) throw new GitHubError("network-unavailable", `${probe.reason}; an account cannot be read from GitHub while it is unreachable, and no login would change that`)
+    throw new GitHubError("login-required", "Account-wide watch needs your GitHub login. Run `gh auth login`, or pass --user <login> to read a public account.")
+  }
   const user = await getJson("https://api.github.com/user")
   if (!user?.login) throw new GitHubError("github-unavailable", "GitHub did not return the signed-in account's login")
   return user.login

package/tools/marketplace/local-transport.mjs

@@ -25,7 +25,7 @@ export const ASSUMED_BY_ADAPTER = Object.freeze([
 ])
 
 function git(repoDir, args, encoding = "utf8") {
-  return execFileSync("git", ["-C", repoDir, ...args], {
+  return execFileSync("git", ["-C", repoDir, ...args], { timeout: 60_000,
     encoding,
     maxBuffer: 512 * 1024 * 1024,
     stdio: ["ignore", "pipe", "pipe"],

package/tools/marketplace/options.mjs

@@ -29,21 +29,24 @@ export const ACCEPTED = Object.freeze({
   parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
   audit: Object.freeze({ valued: ["--out"], flags: ["--drift", "--json", "--offline"], positionals: 1 }),
   inspect: Object.freeze({ valued: ["--out"], flags: ["--full", "--json", "--offline", "--allow-dirty"], positionals: 1 }),
+  add: Object.freeze({ valued: [], flags: ["--update", "--json"], positionals: 2 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
+  lab: Object.freeze({ valued: ["--runs", "--from", "--toolchain", "--out"], flags: ["--json", "--yes", "--verify", "--plugins", "--keep-iso", "--records"], positionals: 2 }),
 })
 
 /** The accepted options of a command in the words a refusal prints: `--runs N, --all, ...`. */
 export function acceptedWords(name) {
   const spec = ACCEPTED[name]
-  const value = (option) => ({ "--out": "FILE", "--runs": "N", "--count": "N", "--offset": "N", "--window": "S", "--settle": "S", "--category": "C", "--tags": "A,B" }[option] || "TEXT")
+  const value = (option) => ({ "--out": "FILE", "--runs": "N", "--count": "N", "--offset": "N", "--window": "S", "--settle": "S", "--category": "C", "--tags": "A,B", "--from": "FILE", "--toolchain": "DIR" }[option] || "TEXT")
   return [...spec.valued.map((option) => `${option} ${value(option)}`), ...spec.flags].join(", ")
 }
 
 /**
  * Read a command line against a command's table. Every token is a known
- * option (valued or not), the value of a valued option, or a positional up
- * to the allowed count; the first token that is none of those is returned
- * as `offending` with a reason, so the command refuses before any preflight.
+ * option (valued or not, a valued one given once), the value of a valued
+ * option (never empty), or a non-empty positional up to the allowed count;
+ * the first token that is none of those is returned as `offending` with a
+ * reason, so the command refuses before any preflight.
  *
  * @param {string[]} args
  * @param {{ valued: string[], flags: string[], positionals: number }} spec
@@ -54,10 +57,18 @@ export function checkArgs(args, spec) {
   const positionals = []
   for (let index = 0; index < args.length; index += 1) {
     const token = args[index]
+    // An empty argument is neither a path, an id nor an option, and is
+    // refused everywhere: measured on 2026-09-19, `omakit audit ""` read
+    // the empty string as no argument and audited every plugin.
+    if (token === "") return { offending: '""', reason: "an empty argument is not a path, an id or an option", options, positionals }
     const [name, inline] = token.startsWith("--") && token.includes("=") ? [token.slice(0, token.indexOf("=")), token.slice(token.indexOf("=") + 1)] : [token, undefined]
     if (spec.valued.includes(name)) {
       const value = inline !== undefined ? inline : args[index + 1]
-      if (value === undefined || (inline === undefined && value.startsWith("-"))) return { offending: token, reason: `${name} needs a value`, options, positionals }
+      if (value === undefined || value === "" || (inline === undefined && value.startsWith("-"))) return { offending: token, reason: `${name} needs a value`, options, positionals }
+      // A valued option is given once. Two values would leave one of them
+      // silently unread (measured on 2026-09-19: the last won, unsaid); a
+      // repeated flag is the flag, and is read once.
+      if (options.has(name)) return { offending: token, reason: `${name} is given twice (${JSON.stringify(options.get(name))} and ${JSON.stringify(value)}); pass it once`, options, positionals }
       options.set(name, value)
       if (inline === undefined) index += 1
     } else if (spec.flags.includes(token)) {

package/tools/marketplace/outcome.mjs

@@ -0,0 +1,244 @@
+// The one contract every command leaves through, stated once here and once
+// in docs/COMMANDS.md, and held per command and per outcome by
+// tests/unit/json-outcomes.test.mjs.
+//
+//   exit      0 is success; 1 is a refusal or a failure the tool means (a
+//             refused submission, drift, a lab that is not ready, a plan a
+//             preflight refused, an error the operating system raised); 2 is
+//             a usage error, and a question a pipe could not answer; a stop
+//             asked for by a signal exits with the signal's own status,
+//             128 plus its number (129 SIGHUP, 130 SIGINT, 143 SIGTERM).
+//   --json    exactly one document on stdout, whatever the outcome:
+//             { command, ok, error, ...the command's own document }, where
+//             `error` is null on success and { code, message, remedy } on
+//             any other exit, `remedy` never null; the failure's sentence
+//             is on stderr too, and nothing else is.
+//   stdout    the command's text on exit 0; on any other exit the text (a
+//             report with its verdict, or the failure block) is on stderr,
+//             so stdout carries nothing a parser would mistake for a result.
+//             A long-running command's live narration (weigh's restarts, the
+//             lab's suite lines) is written as it happens and is not the
+//             result: on stdout for a person, on stderr under --json.
+//   --out     the run's document, the same JSON --json prints, written to the
+//             file on every outcome but a usage error, whose command line is
+//             not trusted; with --json, stdout then carries nothing at all,
+//             and without it the text says where the file went.
+//
+// Measured on 2026-09-19 by an acceptance tester: seven commands shaped
+// their documents seven ways, `lab prune --json` printed nothing, `watch`
+// exited 2 on a verdict, `add` on EACCES carried `remedy: null`, `lab
+// inspect` and `audit` wrote a failing result to stdout only, and a failed
+// `lab prove --json --out` created no file (docs/evidence/ux/
+// 2026-09-19-acceptance.json, finding 2). Every one of those is one place
+// now, this file, and a command that does not pass through it cannot print.
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { action, colourEnabled, GUTTER, labelled, mark, styler, verdict, withOutputStream, wrap } from "./style.mjs"
+import { withHomeAbbreviated } from "./paths.mjs"
+
+export const EXIT = Object.freeze({ ok: 0, refused: 1, usage: 2 })
+
+/** The shell's convention for a process that stopped on a signal: 128 plus the signal number. */
+export const SIGNAL_EXIT = Object.freeze({ SIGHUP: 129, SIGINT: 130, SIGTERM: 143 })
+
+export function signalExit(signal) {
+  return SIGNAL_EXIT[signal] ?? SIGNAL_EXIT.SIGINT
+}
+
+/** The exit status a failure code means, the same for every command. */
+export function exitFor(code, signal = null) {
+  if (code === "usage" || code === "not-confirmed") return EXIT.usage
+  if (code === "interrupted") return signalExit(signal)
+  return EXIT.refused
+}
+
+/**
+ * What to do about an error the operating system raised, by its code: the
+ * one action, since a remedy is never null. Measured on 2026-09-19: `add`
+ * into a read-only directory carried EACCES and `remedy: null`.
+ */
+export const OS_REMEDY = Object.freeze({
+  EACCES: "Make the directory writable (chmod u+w <dir>), or run it in a directory you own.",
+  EPERM: "Make the directory writable (chmod u+w <dir>), or run it in a directory you own.",
+  EROFS: "The filesystem is read-only; copy the tree somewhere writable and run it there.",
+  ENOSPC: "Free disk space, then run it again.",
+  EDQUOT: "Free disk space under your quota, then run it again.",
+  ENOENT: "Check the path: it does not exist.",
+  ENOTDIR: "Pass a directory where one is meant; a file is in its place.",
+  EISDIR: "Pass a file where one is meant; a directory is in its place.",
+  EEXIST: "Move what is in the way, then run it again.",
+  ENOTEMPTY: "Move what is in the way, then run it again.",
+  EBUSY: "Wait for the process that holds it, then run it again.",
+  EMFILE: "Close some files or raise the descriptor limit (ulimit -n), then run it again.",
+  ENFILE: "Close some files or raise the descriptor limit (ulimit -n), then run it again.",
+  ELOOP: "Remove the symbolic link loop in the path, then run it again.",
+  ENAMETOOLONG: "Use a shorter path.",
+  ETIMEDOUT: "Connect to the network, then run it again.",
+  ECONNRESET: "Connect to the network, then run it again.",
+  ECONNREFUSED: "Connect to the network, then run it again.",
+  ENOTFOUND: "Connect to the network, then run it again.",
+  EAI_AGAIN: "Connect to the network, then run it again.",
+  ENETUNREACH: "Connect to the network, then run it again.",
+  EHOSTUNREACH: "Connect to the network, then run it again.",
+})
+
+/** The remedy when no table names one: where to read and what to run. */
+export const GENERAL_REMEDY = "Read the sentence above; `omakit doctor` names what this machine lacks, and docs/COMMANDS.md states the command's contract."
+
+/**
+ * The remedy for a failure, never null: the module's own, else the
+ * command table's, else the operating system's by errno, else the general one.
+ */
+export function remedyFor(code, remedy, table = {}) {
+  if (typeof remedy === "string" && remedy.trim()) return remedy
+  return table[code] || OS_REMEDY[code] || GENERAL_REMEDY
+}
+
+/**
+ * A message as one sentence: trimmed, ending in exactly one full stop
+ * (a question or an exclamation keeps its own mark). Measured on 2026-09-19:
+ * `audit` appended a full stop to a sentence that had one, "without it..".
+ */
+export function sentence(text) {
+  const trimmed = String(text ?? "").trim().replace(/\s+$/, "")
+  if (!trimmed) return ""
+  if (/[?!]$/.test(trimmed)) return trimmed
+  return `${trimmed.replace(/\.+$/, "")}.`
+}
+
+/**
+ * The document every command prints under --json: the envelope, then the
+ * command's own document. A document that is a list is carried as `rows`;
+ * the three envelope keys are the envelope's, whatever a document says.
+ */
+export function envelope({ command, exit, error = null, document = null }) {
+  const ok = exit === 0
+  const body = document === null || document === undefined ? {} : Array.isArray(document) ? { rows: document } : typeof document === "object" ? document : { value: document }
+  const { command: _command, ok: _ok, error: _error, ...rest } = body
+  return { command, ok, error: ok ? null : error, ...rest }
+}
+
+/**
+ * A failure as an error object for the envelope: the code, the sentence,
+ * the remedy (never null), and anything the caller listed beside them
+ * (`missing`, `usage`), in that order.
+ */
+export function failure({ code, message, remedy, table = {}, ...extra }) {
+  return { code, message: sentence(message), remedy: remedyFor(code, remedy, table), ...extra }
+}
+
+/** The failure block for a person: `█ FAIL  code`, the sentence in the gutter, the listed items, the arrow. */
+export function failureBlock(error, c, { body = () => [] } = {}) {
+  const lines = [`${mark("fail", c)}${c("name", error.code)}`, ...wrap(error.message, { indent: GUTTER }, c)]
+  for (const item of error.missing || []) {
+    lines.push(`${" ".repeat(GUTTER)}${c("name", item.what)}`, ...labelled("costs", withHomeAbbreviated(item.cost), c))
+    if (item.command) lines.push(...action(withHomeAbbreviated(item.command), c))
+  }
+  lines.push(...body(c))
+  lines.push(...action(error.remedy, c))
+  return lines
+}
+
+/** A failure in a verdict register (`█ NOT WEIGHED  sentence`, then the arrow), for the commands whose report closes on a word. */
+export function verdictBlock(word, error, c) {
+  return [...verdict("fail", word, error.message, c), ...action(error.remedy, c, { indent: 0 })]
+}
+
+/** The value of a valued option on a command line, `--name value` or `--name=value`. */
+export function optionValue(args, name) {
+  let value
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === name) value = args[index + 1]
+    else if (args[index].startsWith(`${name}=`)) value = args[index].slice(name.length + 1)
+  }
+  return value
+}
+
+/**
+ * How a command ends: one call that writes the document, the text and the
+ * file the contract above names, and sets the exit status.
+ *
+ * @param {{ command: string, args: string[], exit: number, document?: object|any[]|null,
+ *           error?: { code: string, message: string, remedy: string }|null,
+ *           human?: ((colour: boolean) => string)|string|null,
+ *           render?: ((error: object, c: Function) => string[])|null,
+ *           stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream }} outcome
+ *   `human` is the command's text for a person (a report, or nothing when
+ *   the failure block is all there is); `render` draws a failure in the
+ *   command's own register instead of the block. An `error` is required
+ *   when `exit` is not 0.
+ * @returns {number} the exit status, also set on process.exitCode
+ */
+export function conclude({ command, args, exit, document = null, error = null, human = null, render = null, stdout = process.stdout, stderr = process.stderr }) {
+  const json = args.includes("--json")
+  const out = optionValue(args, "--out")
+  if (exit !== 0 && !error) throw new Error(`outcome: exit ${exit} for ${command} without an error to report`)
+  let doc = envelope({ command, exit, error, document })
+  let written = false
+  // A usage error refused the command line whole, so no option on it is
+  // trusted, --out included: the document stays on stdout. Measured on
+  // 2026-09-19 by the acceptance matrix: `audit --out a --out b` was refused
+  // for the repeat and still wrote the refusal to b.
+  if (out && error?.code !== "usage") {
+    try {
+      mkdirSync(dirname(resolve(out)), { recursive: true })
+      writeFileSync(resolve(out), `${JSON.stringify(doc, null, 2)}\n`)
+      written = true
+    } catch (problem) {
+      // A file that could not be written is a failure of the run, reported
+      // like any other and carried in the document that reaches stdout.
+      exit = EXIT.refused
+      error = failure({ code: problem.code || "out-unwritable", message: `--out ${resolve(out)} could not be written: ${problem.message}` })
+      doc = envelope({ command, exit, error, document })
+    }
+  }
+  if (json) {
+    // The document goes to the file when there is one; with no file to go
+    // to (none asked for, or one that could not be written) it is on stdout.
+    if (!written) stdout.write(`${JSON.stringify(doc, null, 2)}\n`)
+    if (exit !== 0) {
+      const c = styler(colourEnabled(stderr))
+      const lines = withOutputStream(stderr, () => (render ? render(error, c) : failureBlock(error, c)))
+      stderr.write(`${lines.join("\n")}\n`)
+    }
+  } else {
+    const stream = exit === 0 ? stdout : stderr
+    const colour = colourEnabled(stream)
+    const c = styler(colour)
+    const pieces = []
+    if (human !== null && human !== undefined) pieces.push(withOutputStream(stream, () => (typeof human === "function" ? human(colour) : String(human))))
+    else if (exit !== 0) pieces.push(withOutputStream(stream, () => (render ? render(error, c) : failureBlock(error, c))).join("\n"))
+    if (written) pieces.push(`${mark("pass", c)}wrote ${withHomeAbbreviated(resolve(out))}`)
+    const text = pieces.filter((piece) => piece !== "").join("\n")
+    if (text) stream.write(text.endsWith("\n") ? text : `${text}\n`)
+  }
+  process.exitCode = exit
+  return exit
+}
+
+/**
+ * How a failure state leaves: not through `process.exit()` in the middle
+ * of a write. A write to a pipe is asynchronous on some platforms, and an
+ * exit right behind it drops the bytes (measured on 2026-09-19 by a first
+ * user whose `omakit audit --wat` came back with exit 2 and an empty
+ * stderr). So a failure throws this, the dispatcher catches it, waits for
+ * both streams to drain, and exits with the code.
+ */
+export class Exit extends Error {
+  constructor(exit) {
+    super(`exit ${exit}`)
+    this.exit = exit
+  }
+}
+
+/** Both streams flushed, then the exit; a closed pipe on either is not an error worth a trace. */
+export async function leave(exit) {
+  for (const stream of [process.stdout, process.stderr]) {
+    await new Promise((resolveDrain) => {
+      if (stream.destroyed || stream.writableEnded) return resolveDrain()
+      stream.write("", () => resolveDrain())
+    }).catch(() => {})
+  }
+  process.exit(exit)
+}