omakit 0.1.2 → 0.1.4

package/tools/marketplace/registry.mjs

@@ -1,8 +1,7 @@
-// The plugin-id and repository universe, read from the pinned marketplace
-// checkout. Like the submission contract, nothing here is hardcoded: the
-// reserved namespace is read out of the marketplace's own catalog builder, the
-// listed ids out of the published catalog and the registry sources, and the
-// retired ids out of `registry.json`.
+// The plugin-id and repository universe. Like the submission contract, nothing
+// here is hardcoded: the reserved namespace is read out of the marketplace's
+// own catalog builder, the listed ids out of the published catalog and the
+// registry sources, and the retired ids out of `registry.json`.
 //
 // Measured reason these three checks exist (docs/MEASUREMENTS.md M2): the
 // marketplace refuses a submission whose id is already listed
@@ -13,15 +12,31 @@
 // median submission-to-publication time rose sevenfold between 2026-W33 and
 // 2026-W36, and it is knowable before submitting from data the marketplace
 // publishes.
+//
+// Two kinds of file, two sources (docs/MEASUREMENTS.md M7). The catalog
+// builder is code, and code is only ever read from the pin: it moves a few
+// times a month and must never be fetched and executed unreviewed. The
+// registry and the catalog are data, and the pin's copy of them is stale
+// within hours: registry.json changed in 4,201 of the marketplace's 4,293
+// commits in the 30 days to 2026-09-13, about 140 a day. So those two files
+// are read from the marketplace's current default-branch HEAD when the network
+// is there, at the exact commit `defaultBranchHead()` resolved so they cannot
+// disagree with each other, and from the pin when it is not or when the caller
+// asks for --offline. Every result says which, with the commit.
 
-import { readFileSync } from "node:fs"
-import { join } from "node:path"
-import { requirePin } from "./pin.mjs"
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
+import { defaultBranchHead, getJson } from "./github.mjs"
+import { omakitCacheDir } from "./paths.mjs"
 
 export const CATALOG_PATH = "site/catalog.json"
 export const REGISTRY_PATH = "registry.json"
 export const CATALOG_BUILDER_PATH = "scripts/build-catalog.mjs"
 
+/** The only two marketplace files ever read from HEAD. Everything else comes from the pin. */
+export const LIVE_PATHS = Object.freeze([REGISTRY_PATH, CATALOG_PATH])
+
 export class RegistryError extends Error {
   constructor(code, message) {
     super(message)
@@ -65,18 +80,181 @@ function repositorySlug(value) {
 }
 
 /**
- * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ * The one URL shape a live registry file is read from: one of LIVE_PATHS at
+ * one explicit 40-character commit on the marketplace's raw file host. Never
+ * a branch name, so the two files always come from the same commit and the
+ * commit named in the output is the one they came from; never a path outside
+ * LIVE_PATHS, so nothing executable can arrive this way.
+ */
+export function liveFileUrl(commit, path) {
+  if (!/^[0-9a-f]{40}$/.test(String(commit))) {
+    throw new RegistryError("usage", `a live registry file is read at a 40-character commit, not "${commit}"`)
+  }
+  if (!LIVE_PATHS.includes(path)) {
+    throw new RegistryError("usage", `${path} is never read from HEAD; only ${LIVE_PATHS.join(" and ")} are`)
+  }
+  const raw = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "https://raw.githubusercontent.com/")
+  return `${raw}/${commit}/${path}`
+}
+
+/** Where the live files for one commit are kept: beside the pin, never inside it. */
+export function liveCacheDir(commit, cacheRoot = omakitCacheDir("registry")) {
+  return join(cacheRoot, commit)
+}
+
+/** A cached commit is one whose meta.json, written last, names every file present. */
+function readCached(liveCache) {
+  try {
+    const meta = JSON.parse(readFileSync(join(liveCache, "meta.json"), "utf8"))
+    if (typeof meta.fetchedAt !== "string" || JSON.stringify(meta.paths) !== JSON.stringify(LIVE_PATHS)) return null
+    const files = {}
+    for (const path of LIVE_PATHS) files[path] = JSON.parse(readFileSync(join(liveCache, path), "utf8"))
+    return { fetchedAt: meta.fetchedAt, files }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * One directory per commit, the files first and meta.json last, so a run that
+ * dies mid-write leaves a directory readCached() does not accept. Older
+ * commits are removed: at about 140 registry commits a day, keeping every one
+ * would grow the cache by the measured 13 MB per run.
+ */
+function writeCached(cacheRoot, commit, fetchedAt, files) {
+  const liveCache = liveCacheDir(commit, cacheRoot)
+  rmSync(liveCache, { recursive: true, force: true })
+  for (const path of LIVE_PATHS) {
+    mkdirSync(dirname(join(liveCache, path)), { recursive: true })
+    writeFileSync(join(liveCache, path), JSON.stringify(files[path]))
+  }
+  writeFileSync(join(liveCache, "meta.json"), `${JSON.stringify({ commit, fetchedAt, paths: LIVE_PATHS }, null, 2)}\n`)
+  for (const entry of readdirSync(cacheRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && entry.name !== commit) rmSync(join(cacheRoot, entry.name), { recursive: true, force: true })
+  }
+}
+
+/**
+ * The registry and the catalog, from the marketplace's current default-branch
+ * HEAD when the network is there and from the pin when it is not. Never
+ * throws for a network reason: a HEAD that cannot be read falls back to the pin
+ * and says so in `reason`. The pinned checkout is never written to; a fetched
+ * pair is cached under `cacheRoot/<commit>/`.
+ *
+ * `resolveHead`, `fetchJson`, `cacheRoot` and `now` are injectable for tests;
+ * the defaults are the tool's one HEAD resolver and its one GET call site.
+ *
+ * @param {{ repoRoot?: string, pinDir?: string, offline?: boolean,
+ *           resolveHead?: (url: string) => Promise<{ commit: string }>,
+ *           fetchJson?: (url: string) => Promise<object>, cacheRoot?: string,
+ *           now?: () => string }} [options]
+ * @returns {Promise<{ source: "head"|"pin", commit: string, fetchedAt: string|null,
+ *                     reason: string|null, fallback: { what: string, code: string, message: string }|null,
+ *                     registry: object, catalog: object }>}
+ *   `reason` is the whole story, for `--json`; `fallback` is its parts, for
+ *   the one line a person reads (registrySourceDetail).
+ */
+export async function liveRegistry(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const resolveHead = options.resolveHead || defaultBranchHead
+  const fetchJson = options.fetchJson || getJson
+  const cacheRoot = options.cacheRoot || omakitCacheDir("registry")
+  const now = options.now || (() => new Date().toISOString())
+  const fromPin = (reason, fallback = null) => ({
+    source: "pin",
+    commit: MARKETPLACE_PIN.commit,
+    fetchedAt: null,
+    reason,
+    fallback,
+    registry: readJson(pinDir, REGISTRY_PATH),
+    catalog: readJson(pinDir, CATALOG_PATH),
+  })
+  const failed = (what, error) => {
+    const code = error?.code || "error"
+    const message = String(error?.message || error)
+    return fromPin(`${what} (${code}): ${message}`, { what, code, message })
+  }
+  if (options.offline) return fromPin("--offline")
+
+  let commit
+  try {
+    commit = String((await resolveHead(MARKETPLACE_PIN.repository)).commit).toLowerCase()
+  } catch (error) {
+    return failed("HEAD unreadable", error)
+  }
+  if (commit === MARKETPLACE_PIN.commit) {
+    // HEAD is the pin, so the pin's files are HEAD's files: nothing to fetch.
+    return { ...fromPin(null), source: "head", fetchedAt: now() }
+  }
+
+  const cached = readCached(liveCacheDir(commit, cacheRoot))
+  if (cached) {
+    return { source: "head", commit, fetchedAt: cached.fetchedAt, reason: null, fallback: null, registry: cached.files[REGISTRY_PATH], catalog: cached.files[CATALOG_PATH] }
+  }
+
+  const files = {}
+  try {
+    for (const path of LIVE_PATHS) files[path] = await fetchJson(liveFileUrl(commit, path))
+  } catch (error) {
+    return failed(`registry at ${commit} unreadable`, error)
+  }
+  const fetchedAt = now()
+  try {
+    mkdirSync(cacheRoot, { recursive: true })
+    writeCached(cacheRoot, commit, fetchedAt, files)
+  } catch {
+    // A cache that cannot be written costs the next run a refetch, nothing else.
+  }
+  return { source: "head", commit, fetchedAt, reason: null, fallback: null, registry: files[REGISTRY_PATH], catalog: files[CATALOG_PATH] }
+}
+
+/**
+ * How a check names where its registry data came from. Short hash for the
+ * pin, which the docs name that way; the full commit for HEAD, which nothing
+ * else names.
+ *
+ * A fallback is one clause, not the whole story: the transport error's own
+ * parenthetical and its "while reading <path>" tail are dropped and the
+ * failure code takes their place, so the person reads
+ * "registry at the pin 38060f89; HEAD unreadable: github.com did not answer
+ * (network-unavailable)" on one line. Measured before this: the full text
+ * nested three sets of parentheses and wrapped to three lines at 80 columns.
+ * `--json` keeps the whole text under `registry.reason`.
+ */
+export function registrySourceDetail(live) {
+  if (live.source === "head") return `registry at ${live.commit}, read ${live.fetchedAt}`
+  const pin = `registry at the pin ${live.commit.slice(0, 8)}`
+  if (!live.fallback) return live.reason === "--offline" ? `${pin} (offline)` : pin
+  const { what, code, message } = live.fallback
+  const clause = message.replace(/ while reading .*$/, "").replace(/\s*\([^()]*\)\s*$/, "").trim()
+  const short = what.replace(/^registry at ([0-9a-f]{40}) unreadable$/, (_, sha) => `HEAD ${sha.slice(0, 7)} unreadable`)
+  return `${pin}; ${short}: ${clause} (${code})`
+}
+
+/**
+ * @param {{ repoRoot?: string, pinDir?: string, registry?: object, catalog?: object }} [options]
+ *   `registry` and `catalog` are the parsed files from liveRegistry(); without
+ *   them the pin's copies are read.
  * @returns {{ reservedPrefix: string, listedIds: Set<string>, retiredIds: Set<string>,
- *             listedRepositories: Set<string>, counts: object }}
+ *             listedRepositories: Set<string>, listedBy: Map<string, string>, counts: object }}
+ *   `listedBy` names the repository slug that lists each id, where the
+ *   registry or catalog says which, so a taken id can be blamed on a
+ *   repository and told apart from the subject's own listing.
  */
 export function idUniverse(options = {}) {
   const pinDir = options.pinDir || requirePin(options.repoRoot).dir
-  const catalog = readJson(pinDir, CATALOG_PATH)
-  const registry = readJson(pinDir, REGISTRY_PATH)
+  const catalog = options.catalog || readJson(pinDir, CATALOG_PATH)
+  const registry = options.registry || readJson(pinDir, REGISTRY_PATH)
 
   const listedIds = new Set()
+  const listedBy = new Map()
+  const listed = (id, repo) => {
+    listedIds.add(id)
+    const slug = repositorySlug(repo)
+    if (slug && !listedBy.has(id)) listedBy.set(id, slug)
+  }
   for (const plugin of Array.isArray(catalog.plugins) ? catalog.plugins : []) {
-    if (typeof plugin?.id === "string" && plugin.id) listedIds.add(plugin.id)
+    if (typeof plugin?.id === "string" && plugin.id) listed(plugin.id, plugin.repo)
   }
   const catalogIds = listedIds.size
 
@@ -86,17 +264,17 @@ export function idUniverse(options = {}) {
     const slug = repositorySlug(source?.repo)
     if (slug) listedRepositories.add(slug)
     if (source?.plugins && typeof source.plugins === "object" && !Array.isArray(source.plugins)) {
-      for (const id of Object.keys(source.plugins)) listedIds.add(id)
+      for (const id of Object.keys(source.plugins)) listed(id, source.repo)
     }
     if (Array.isArray(source?.plugins)) {
       for (const entry of source.plugins) {
         const id = typeof entry === "string" ? entry : entry?.id
-        if (id) listedIds.add(id)
+        if (id) listed(id, source.repo)
       }
     }
-    if (typeof source?.catalog?.id === "string") listedIds.add(source.catalog.id)
+    if (typeof source?.catalog?.id === "string") listed(source.catalog.id, source.repo)
     for (const id of source?.automatedSecurityBaseline?.pluginIds || []) {
-      if (typeof id === "string") listedIds.add(id)
+      if (typeof id === "string") listed(id, source.repo)
     }
   }
 
@@ -112,6 +290,7 @@ export function idUniverse(options = {}) {
     listedIds,
     retiredIds,
     listedRepositories,
+    listedBy,
     counts: {
       catalogPlugins: catalogIds,
       registrySources: sources.length,
@@ -185,7 +364,11 @@ export function figure(n) {
 
 /**
  * @param {{ id: string, repositoryUrl?: string|null }} subject
- * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string }> }}
+ * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string, repository?: string|null, sameRepository?: boolean }> }}
+ *   A `plugin-id-listed` problem names the repository that lists the id
+ *   (`repository`, a slug, or null when the registry does not say) and
+ *   whether that is the subject's own (`sameRepository`), because the two
+ *   have different remedies: another id, or nothing to submit at all.
  */
 export function checkIdentity(universe, subject) {
   const problems = []
@@ -194,6 +377,7 @@ export function checkIdentity(universe, subject) {
     problems.push({ code: "plugin-id-missing", detail: "the root manifest declares no id" })
     return { ok: false, problems }
   }
+  const slug = repositorySlug(subject.repositoryUrl)
   if (id.toLowerCase().startsWith(universe.reservedPrefix)) {
     problems.push({
       code: "reserved-plugin-id",
@@ -204,11 +388,17 @@ export function checkIdentity(universe, subject) {
     problems.push({ code: "plugin-id-retired", detail: `"${id}" was used by a previous listing (registry.json retiredPluginIds)` })
   }
   if (universe.listedIds.has(id)) {
-    problems.push({ code: "plugin-id-listed", detail: `"${id}" is already listed` })
+    const repository = universe.listedBy?.get(id) || null
+    const sameRepository = Boolean(repository && slug && repository === slug)
+    problems.push({
+      code: "plugin-id-listed",
+      detail: `"${id}" is already listed${repository ? ` by ${repository}` : ""}`,
+      repository,
+      sameRepository,
+    })
   }
-  const slug = repositorySlug(subject.repositoryUrl)
   if (slug && universe.listedRepositories.has(slug)) {
-    problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed` })
+    problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed`, repository: slug, sameRepository: true })
   }
   return { ok: problems.length === 0, problems }
 }

package/tools/marketplace/report.mjs

@@ -23,9 +23,10 @@ import {
 
 const body = " ".repeat(GUTTER)
 
-/** The state a check renders in: an advisory failure is a note, not a FAIL. */
+/** The state a check renders in: an advisory failure is a note, not a FAIL, and a check that waited on another is a question. */
 function stateOf(check) {
   if (check.verdict === "pass") return "pass"
+  if (check.verdict === "unknown") return "unknown"
   return check.severity === "advisory" ? "advisory" : "fail"
 }
 
@@ -53,7 +54,7 @@ function checkBlock(check, c) {
           ? `${body}${c("fail", "-")} ${c("placeholder", line.trimStart().slice(2))}`
           : `${" ".repeat(GUTTER + STEP)}${c("placeholder", line.trimStart())}`)))
     }
-    if (check.remedy) out.push(...action(check.remedy, c))
+    for (const remedy of [].concat(check.remedy || [])) out.push(...action(remedy, c))
     // The measured reason is the point of the check, so it is not dimmed: only
     // its label is grey, and on a low-contrast theme the number still reads.
     out.push(...labelled("why", check.why, c))
@@ -69,12 +70,14 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   out.push(...field("marketplace", `${result.pin.commit}, baseline ${result.pin.baselineVersion}, ${result.pin.enforcementMode}`, c))
   out.push("")
 
-  // Passing checks run together; anything else gets a blank line on each side,
+  // Passing checks run together, and so does a check that waited on another:
+  // both are two quiet lines. Anything else gets a blank line on each side,
   // collapsed where two blocks meet.
+  const quiet = (state) => state === "pass" || state === "unknown"
   let previous = "pass"
   for (const [index, check] of result.checks.entries()) {
     const state = stateOf(check)
-    if (index > 0 && (state !== "pass" || previous !== "pass")) out.push("")
+    if (index > 0 && (!quiet(state) || !quiet(previous))) out.push("")
     out.push(...checkBlock(check, c))
     previous = state
   }
@@ -89,13 +92,17 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   }
 
   if (!result.ready) {
+    // Root causes only: a check that waited on a failed one is not listed,
+    // and the count says how many waited.
     const failed = result.checks.filter((check) => result.blocking.includes(check.id))
+    const waited = result.checks.filter((check) => check.verdict === "unknown").length
     const count = failed.length === 1 ? "1 blocking check" : `${failed.length} blocking checks`
-    out.push(...verdict("fail", "REFUSED", `${count} failed, so no submission body is produced.`, c))
+    const waiting = waited ? ` ${waited === 1 ? "1 check" : `${waited} checks`} could not run until ${failed.length === 1 ? "it passes" : "they pass"}.` : ""
+    out.push(...verdict("fail", "REFUSED", `${count} failed, so no submission body is produced.${waiting}`, c))
     out.push("")
     for (const check of failed) {
       out.push(`${body}${c("name", check.id)}`)
-      if (check.remedy) out.push(...action(check.remedy, c))
+      if (check.remedy) for (const remedy of [].concat(check.remedy)) out.push(...action(remedy, c))
       else out.push(...wrap(check.detail, { indent: GUTTER }, c))
       out.push("")
     }

package/tools/marketplace/setup.mjs

@@ -11,8 +11,6 @@
 // and stops, which is the same contract every other command here keeps.
 
 import { execFileSync } from "node:child_process"
-import { existsSync } from "node:fs"
-import { delimiter, join } from "node:path"
 import { banner } from "./banner.mjs"
 import { credential, UNAUTHENTICATED_LIMIT } from "./github.mjs"
 import { ensurePin, marketplacePinDir, pinDiskUsage } from "./pin.mjs"
@@ -21,6 +19,7 @@ import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
 import { TAGLINE } from "./usage.mjs"
 import { installCompletion } from "./completion.mjs"
 import { submissionContract } from "./form.mjs"
+import { pathHint } from "./path-hint.mjs"
 
 function version(command) {
   try {
@@ -32,11 +31,6 @@ function version(command) {
   }
 }
 
-/** Is `omakit` reachable as a bare command, without asking a shell? */
-export function onPath(name = "omakit", env = process.env) {
-  return (env.PATH || "").split(delimiter).some((dir) => dir && existsSync(join(dir, name)))
-}
-
 /**
  * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream }} options
  */
@@ -101,9 +95,14 @@ export async function setup({ repoRoot, entryPoint, stream = process.stdout }) {
   for (const line of wrap("Every rule omakit checks is read from that checkout, at that exact commit. It never moves on its own. `omakit doctor` says when it is behind.", {}, c)) out(line)
   out()
 
-  if (!onPath()) {
-    step("info", "`omakit` is not on your PATH yet. This puts it there:")
-    fix(`ln -s ${entryPoint} ~/.local/bin/omakit`)
+  // The hint is for the install that is here: a symlink for a clone, the npm
+  // prefix's bin on PATH for a package, in the shell in $SHELL (path-hint.mjs).
+  const reach = pathHint({ repoRoot, entryPoint })
+  if (!reach.reachable) {
+    step("info", reach.line
+      ? `${reach.reason} This puts it there${reach.where ? `; keep it in ${reach.where}` : ""}:`
+      : reach.reason)
+    if (reach.line) fix(reach.line)
     out()
   }
 

package/tools/marketplace/submit.mjs

@@ -14,7 +14,7 @@
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
 import { requirePin } from "./pin.mjs"
 import { submissionContract, resolveCategory, resolveTags } from "./form.mjs"
-import { idUniverse, checkIdentity, baselineFigures, figure } from "./registry.mjs"
+import { idUniverse, checkIdentity, baselineFigures, figure, liveRegistry, registrySourceDetail } from "./registry.mjs"
 import { readTree } from "./tree.mjs"
 import { inspectTree } from "./plugin.mjs"
 import { findAgentControl, REMEDY as AGENT_CONTROL_REMEDY } from "./agent-control.mjs"
@@ -23,6 +23,39 @@ import { renderIssue, verifyAgainstOfficialParser } from "./issue.mjs"
 import { defaultBranchHead } from "./github.mjs"
 import { REFRESH_ACTION } from "./watch.mjs"
 import { omakitCacheDir } from "./paths.mjs"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+/**
+ * The marketplace's own name for the verification action that lists a newer
+ * commit of an already listed plugin, read from the pin rather than typed:
+ * a form option retyped here would drift by a word, and a person would be
+ * sent to choose something the form no longer offers.
+ */
+async function newerCommitAction(pinDir) {
+  const verification = await import(pathToFileURL(join(pinDir, "scripts/plugin-verification-request.mjs")).href)
+  return verification.upstreamUpdateVerificationAction
+}
+
+/**
+ * One arrow per cause, in this order, so a person fixes the thing that is
+ * actually wrong. Measured before this: an id listed by its own repository
+ * was told to "choose an unused plugin id outside the reserved namespace",
+ * which is the remedy for a different failure, and an author who followed
+ * it would have renamed a plugin the marketplace already lists.
+ */
+function identityRemedies(identity, universe, newerCommit) {
+  const remedies = []
+  const codes = new Set(identity.problems.map((problem) => problem.code))
+  if (codes.has("reserved-plugin-id")) remedies.push(`Choose a plugin id outside the reserved ${universe.reservedPrefix}* namespace.`)
+  if (codes.has("plugin-id-retired")) remedies.push("That id was retired by the marketplace and cannot be reused; choose another.")
+  const taken = identity.problems.find((problem) => problem.code === "plugin-id-listed" && !problem.sameRepository)
+  if (taken) remedies.push(taken.repository ? `That id is taken by ${taken.repository}; choose another.` : "That id is already listed; choose another.")
+  if (identity.problems.some((problem) => problem.sameRepository)) {
+    remedies.push(`This plugin is already listed, so there is nothing to submit. To get a newer commit listed, use the marketplace's verification form and choose "${newerCommit}"; \`omakit watch <the submission issue>\` shows which commit is listed now.`)
+  }
+  return remedies
+}
 
 export class SubmitError extends Error {
   constructor(code, message) {
@@ -32,23 +65,56 @@ export class SubmitError extends Error {
   }
 }
 
+/**
+ * A check has three verdicts. `pass` and `fail` are its own. `unknown` is
+ * for a check that could not run because one it depends on failed: it is
+ * rendered as a question, its detail names what it waited on, and it counts
+ * in neither `blocking` nor `advisory`, so a refusal lists root causes only.
+ * Measured before this: a run with no --category and no --tags on a listed
+ * plugin said "6 blocking checks failed" for two causes, because headings,
+ * checklist and official-parser each failed for want of a body nobody could
+ * render yet, and the closing refusal listed them with "not rendered" where
+ * a remedy goes.
+ */
 function check(id, fields) {
+  const waitedOn = (fields.waitedOn || []).filter(Boolean)
   return {
     id,
     source: fields.source,
     why: fields.why,
     severity: fields.severity || "blocking",
-    verdict: fields.verdict ? "pass" : "fail",
-    detail: fields.detail || "",
+    verdict: waitedOn.length ? "unknown" : fields.verdict ? "pass" : "fail",
+    detail: waitedOn.length ? `not checked: it needs ${waitedOn.join(" and ")} to pass first` : fields.detail || "",
     paths: fields.paths || [],
-    remedy: fields.remedy || null,
+    // One arrow, or one per cause in the order they should be read.
+    remedy: waitedOn.length ? null : Array.isArray(fields.remedy) ? (fields.remedy.length ? fields.remedy : null) : fields.remedy || null,
   }
 }
 
+/**
+ * What `submit` needs on the command line, decided before any check runs:
+ * the category and the tags are editorial choices nobody else can make, and
+ * a run without them has nothing to render. The controlled values come from
+ * the form at the pin, so the usage message lists exactly what the form
+ * accepts. Null when nothing is missing.
+ *
+ * @returns {{ missing: string[], categories: string[], tags: string[], maximumTags: number }|null}
+ */
+export function missingSubmitFlags(contract, { category, tags } = {}) {
+  const missing = []
+  if (!String(category ?? "").trim()) missing.push("--category")
+  if (!(Array.isArray(tags) ? tags : String(tags ?? "").split(",")).some((value) => String(value).trim())) missing.push("--tags")
+  if (!missing.length) return null
+  return { missing, categories: [...contract.categories], tags: [...contract.tagLabels], maximumTags: contract.maximumTags }
+}
+
 /**
  * @param {{ repoRoot: string, target: string, category?: string, tags?: string|string[],
  *           notes?: string, suggestedTag?: string, pluginName?: string,
- *           allowDirty?: boolean, offline?: boolean }} options
+ *           allowDirty?: boolean, offline?: boolean,
+ *           readRegistry?: typeof liveRegistry }} options
+ *   `readRegistry` is injectable for tests; the default reads the marketplace's
+ *   current HEAD, or the pin with `offline`.
  */
 export async function submitPreflight(options) {
   const { repoRoot } = options
@@ -57,11 +123,14 @@ export async function submitPreflight(options) {
   const phase = options.onPhase || (() => {})
 
   phase("verifying the pinned marketplace checkout")
-  const { identity: pinIdentity } = requirePin(repoRoot)
+  const { dir: pinDir, identity: pinIdentity } = requirePin(repoRoot)
   phase("reading the submission contract from the pin")
   const contract = await submissionContract({ repoRoot })
-  phase("reading the listed and retired plugin ids")
-  const universe = idUniverse({ repoRoot })
+  phase(options.offline ? "reading the listed and retired plugin ids from the pin" : "reading the marketplace's current registry")
+  const live = await (options.readRegistry || liveRegistry)({ repoRoot, offline: options.offline === true })
+  const universe = idUniverse({ repoRoot, registry: live.registry, catalog: live.catalog })
+  // The documented figures are the pin's by design: they are cited in prose
+  // that a test holds to the pin, so they never move between two runs.
   const figures = baselineFigures({ repoRoot })
 
   phase("resolving the subject commit")
@@ -143,14 +212,15 @@ export async function submitPreflight(options) {
   // --- identity -------------------------------------------------------------
 
   const identity = checkIdentity(universe, { id: tree.pluginId, repositoryUrl: subject.repository.url })
+  const identityRemedy = identity.ok ? null : identityRemedies(identity, universe, await newerCommitAction(pinDir))
   checks.push(check("identity.available", {
     source: "marketplace-pin",
-    why: `The marketplace refuses \`plugin-id-listed\`, \`plugin-id-retired\`, \`reserved-plugin-id\` and \`submission-repository-listed\`. Checked here against ${universe.counts.listedIds} listed ids, ${universe.counts.retiredIds} retired ids and ${universe.counts.listedRepositories} listed repositories read from the pinned registry and catalog.`,
+    why: `The marketplace refuses \`plugin-id-listed\`, \`plugin-id-retired\`, \`reserved-plugin-id\` and \`submission-repository-listed\`. Checked here against ${figure(universe.counts.listedIds)} listed ids, ${figure(universe.counts.retiredIds)} retired ids and ${figure(universe.counts.listedRepositories)} listed repositories from the registry and catalog at the commit the detail names, and the reserved namespace from the pinned catalog builder. The registry is read from the marketplace's current HEAD when the network is there because the pin's copy is stale within hours: registry.json changed in 4,201 of the marketplace's 4,293 commits in the 30 days to 2026-09-13, about 140 a day (docs/MEASUREMENTS.md M7). Code and the form are only ever read from the pin.`,
     verdict: identity.ok,
-    detail: identity.ok
+    detail: `${identity.ok
       ? `id "${tree.pluginId}" is unused, outside the reserved ${universe.reservedPrefix}* namespace, and the repository is not listed`
-      : identity.problems.map((problem) => `${problem.code}: ${problem.detail}`).join("; "),
-    remedy: identity.ok ? null : "Choose an unused plugin id outside the reserved namespace.",
+      : identity.problems.map((problem) => `${problem.code}: ${problem.detail}`).join("; ")}; ${registrySourceDetail(live)}`,
+    remedy: identityRemedy,
   }))
 
   // --- the submission itself ------------------------------------------------
@@ -185,9 +255,17 @@ export async function submitPreflight(options) {
     remedy: tags.ok ? null : "Pass --tags with 1 to 3 comma-separated values from the list.",
   }))
 
+  // The body needs every field above and the repository URL below; the three
+  // checks that read it wait on whichever of those failed.
+  const bodyWaitsOn = [
+    !pluginName && "submission.title",
+    !category.ok && "submission.category",
+    !tags.ok && "submission.tags",
+    !subject.repository.url && "submission.repository-url",
+  ].filter(Boolean)
   let issue = null
   let parsed = null
-  if (pluginName && category.ok && tags.ok && subject.repository.url) {
+  if (!bodyWaitsOn.length) {
     issue = renderIssue(contract, {
       pluginName,
       repositoryUrl: subject.repository.url,
@@ -211,7 +289,8 @@ export async function submitPreflight(options) {
     source: "marketplace-pin",
     why: `The six form headings must appear in exact order: ${contract.headings.join(", ")}. 11 open submissions are malformed in the body and receive "The validation result could not be published to the issue. A maintainer must review the workflow.", which blames the maintainer for the author's mistake; one of them differs from a valid submission by the single word "Suggested" instead of "Suggest". The headings are rendered from the form at the pin, never typed.`,
     verdict: Boolean(issue),
-    detail: issue ? `${contract.headings.length} headings rendered in form order` : "not rendered: an earlier submission field is missing",
+    detail: issue ? `${contract.headings.length} headings rendered in form order` : "not rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   checks.push(check("submission.checklist", {
@@ -219,6 +298,7 @@ export async function submitPreflight(options) {
     why: `All ${contract.checklist.length} checklist items must be present with their exact text and checked; the marketplace refuses \`submission-checklist-unconfirmed\` otherwise. The text is read from the form at the pin, character for character.`,
     verdict: Boolean(issue),
     detail: issue ? `${contract.checklist.length} items rendered with the form's exact text, all checked` : "not rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   checks.push(check("submission.official-parser", {
@@ -230,6 +310,7 @@ export async function submitPreflight(options) {
         ? `accepted: repo ${parsed.submission.repo}, category ${parsed.submission.category}, tags ${parsed.submission.tags.join(", ")}`
         : `refused by the marketplace's own parser: ${parsed.code}, ${parsed.message}`
       : "not run: no body was rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   // --- the commit the marketplace will actually validate ---------------------
@@ -297,6 +378,7 @@ export async function submitPreflight(options) {
 
   const blocking = checks.filter((entry) => entry.severity === "blocking" && entry.verdict === "fail")
   const advisory = checks.filter((entry) => entry.severity === "advisory" && entry.verdict === "fail")
+  const unknown = checks.filter((entry) => entry.verdict === "unknown")
   const ready = blocking.length === 0
 
   return {
@@ -313,6 +395,12 @@ export async function submitPreflight(options) {
       commit: subject.commit,
       cleanTree: subject.clean,
     },
+    registry: {
+      source: live.source,
+      commit: live.commit,
+      fetchedAt: live.fetchedAt,
+      reason: live.reason,
+    },
     validationCommit: {
       local: subject.commit,
       defaultBranchHead: head?.commit || null,
@@ -325,6 +413,7 @@ export async function submitPreflight(options) {
     ready,
     blocking: blocking.map((entry) => entry.id),
     advisory: advisory.map((entry) => entry.id),
+    unknown: unknown.map((entry) => entry.id),
     issue: ready ? issue : null,
     baseline: preflight.invoked
       ? {