omakit 0.4.0 → 0.4.2

package/tools/marketplace/measure-staleness.mjs

@@ -0,0 +1,76 @@
+// M6 reproduction: open author-fixes issues, bot marker against commits.atom.
+// All remote reads use the existing GET-only client. Unknowns stay unknown.
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { MARKETPLACE_PIN } from "./pin.mjs"
+import { repositoryIssues, getText } from "./github.mjs"
+import { validationWatch } from "./watch.mjs"
+
+export function atomHead(feed, source) {
+  const commit = feed.match(/<id>tag:github\.com,2008:Grit::Commit\/([0-9a-f]{40})<\/id>/i)?.[1]
+    || feed.match(/\/commit\/([0-9a-f]{40})/i)?.[1]
+  if (!commit) throw new Error("No full HEAD commit in commits.atom")
+  return { source, commit: commit.toLowerCase(), branch: null,
+    committedAt: feed.match(/<updated>([^<]+)<\/updated>/)?.[1] || null }
+}
+
+export function stalenessCounts(rows) {
+  const stale = rows.filter((row) => row.verdict === "stale").length
+  const current = rows.filter((row) => row.verdict === "current").length
+  const compared = stale + current
+  return { total: rows.length, compared, stale, current, unknown: rows.length - compared,
+    staleShareOfCompared: compared ? stale / compared : null,
+    staleShareOfPopulation: compared === rows.length && rows.length ? stale / rows.length : null }
+}
+
+export async function measureStaleness(repoRoot, { discover = repositoryIssues, watch = validationWatch, readText = getText } = {}) {
+  const openedAt = new Date().toISOString()
+  const [owner, repository] = new URL(MARKETPLACE_PIN.repository).pathname.slice(1).split("/")
+  const batches = await Promise.all(["needs-fixes", "security-needs-fixes"].map((labels) => discover(owner, repository, undefined, { labels })))
+  const subjects = [...new Map(batches.flat().map((subject) => [subject.number, subject])).values()]
+    .filter((subject) => subject.state === "open" && !subject.pull_request)
+    .sort((a, b) => a.number - b.number)
+  const heads = new Map()
+  function readHead(url) {
+    if (!heads.has(url)) {
+      const source = `${url.replace(/\/$/, "")}/commits.atom`
+      heads.set(url, Promise.resolve().then(async () => atomHead(await readText(source, "application/atom+xml"), source)))
+    }
+    return heads.get(url)
+  }
+  const rows = new Array(subjects.length)
+  let next = 0
+  async function worker() {
+    while (next < subjects.length) {
+      const index = next++
+      const subject = subjects[index]
+      const issueUrl = `${MARKETPLACE_PIN.repository}/issues/${subject.number}`
+      const observedAt = new Date().toISOString()
+      try {
+        const report = await watch({ repoRoot, issueUrl, github: { issue: async () => subject, defaultBranchHead: readHead } })
+        rows[index] = { issue: subject.number, issueUrl, observedAt, completedAt: new Date().toISOString(),
+          repository: report.plugin.repository, validatedCommit: report.validated?.commit || null,
+          validationSource: report.validated?.source || null, validatedAt: report.validated?.checkedAt || null,
+          validationCommentsSource: `https://api.github.com/repos/${owner}/${repository}/issues/${subject.number}/comments`,
+          defaultBranchHead: report.head?.commit || null, headSource: report.head?.source || null,
+          verdict: report.verdict.state,
+          reason: report.verdict.state === "unknown" ? report.verdict.summary : null }
+      } catch (error) {
+        rows[index] = { issue: subject.number, issueUrl, observedAt, completedAt: new Date().toISOString(),
+          repository: null, validatedCommit: null, defaultBranchHead: null, verdict: "unknown",
+          reason: `${error.code || "read-unavailable"}: ${error.message}` }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, subjects.length) }, worker))
+  return { measurement: "M6", date: openedAt.slice(0, 10), openedAt, completedAt: new Date().toISOString(),
+    marketplace: MARKETPLACE_PIN.repository, marketplacePin: MARKETPLACE_PIN.commit,
+    command: "node tools/marketplace/measure-staleness.mjs", sample: false,
+    population: "All open non-PR marketplace issues labelled needs-fixes or security-needs-fixes at discovery",
+    method: "Latest bot security-baseline full commit against default-branch commits.atom HEAD; missing full markers or feeds are unknown; unequal commits are stale, without a claim about ancestry",
+    ...stalenessCounts(rows), rows }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  process.stdout.write(`${JSON.stringify(await measureStaleness(resolve(process.cwd())), null, 2)}\n`)
+}

package/tools/marketplace/report.mjs

@@ -18,7 +18,7 @@
 // screen, and the last screen is the one a person is looking at.
 
 import {
-  action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
+  action, colourEnabled, outputColumns, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
 } from "./style.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
 import { watchIssueTitle } from "./watch.mjs"
@@ -42,7 +42,11 @@ function stateOf(check) {
 export function head(state, id, source, c) {
   const left = `${mark(state, c)}${c("name", id)}`
   const tag = c("punctuation", `[${source}]`)
-  const gap = Math.max(2, COLUMNS - width(left) - width(tag))
+  const columns = outputColumns()
+  if (width(left) + width(tag) + 2 > columns) {
+    return `${left}\n${wrap(`[${source}]`, { indent: GUTTER }).map((line) => c("punctuation", line)).join("\n")}`
+  }
+  const gap = columns - width(left) - width(tag)
   return `${left}${" ".repeat(gap)}${tag}`
 }
 
@@ -78,7 +82,7 @@ function commandLines(command, c) {
       units.push(word)
     }
   }
-  const room = COLUMNS - STEP - " \\".length
+  const room = outputColumns() - STEP - " \\".length
   const lines = []
   let line = ""
   for (const unit of units) {
@@ -262,12 +266,19 @@ export function renderWatchList(result, { colour = colourEnabled() } = {}) {
 /** Compact batch report; exact commits and full discussion remain in JSON. */
 export function renderWatchAll(result, { colour = colourEnabled() } = {}) {
   const c = styler(colour)
-  const out = [...field("account", result.account, c), ...field("issues", `${result.summary.total} checked; ${result.summary.current} current, ${result.summary.stale} stale, ${result.summary.unknown} unknown`, c), ""]
+  const out = [...field("account", result.account, c), ...field("issues", `${result.summary.total} checked; ${result.summary.current} current, ${result.summary.stale} stale, ${result.summary.unknown} unknown`, c)]
+  if (result.reviewCostSummary) {
+    const cost = result.reviewCostSummary
+    const skipped = cost.skipped.length ? `; ${cost.skipped.length} diff(s) skipped (reasons on issue rows)` : ""
+    out.push(...field("review cost", `${cost.manualQueue} of ${cost.pluginUpdates} plugin-update issue(s) on security-review-required; ${cost.docsOnly} docs-only validated diff(s) of ${cost.compared} compared${skipped}`, c))
+  }
+  out.push("")
   for (const row of result.issues) {
     const state = row.report?.verdict.state || "unknown"
     const style = { current: "pass", stale: "fail", unknown: "unknown" }[state]
     out.push(...verdict(style, state.toUpperCase(), `#${row.issue.number} ${watchIssueTitle(row.report?.read.title || row.issue.title)}`, c))
     out.push(...field("issue", row.issue.url, c, { wrapValue: false }))
+    if (row.documentationDiff?.docsOnly === null) out.push(...field("diff skipped", watchIssueTitle(row.documentationDiff.reason), c))
     if (row.error) {
       out.push(...field("read error", watchIssueTitle(`${row.error.code}: ${row.error.message}`), c))
     } else {

package/tools/marketplace/review-cost.mjs

@@ -0,0 +1,107 @@
+// Review cost is advice, never a marketplace rule. Evidence: MEASUREMENTS.md M4 and M9.
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { requirePin } from "./pin.mjs"
+import { token, issue, parseIssueUrl, compareCommits } from "./github.mjs"
+import { discoverWatchIssues, repositoryFor } from "./watch.mjs"
+import { repositorySlug } from "./registry.mjs"
+
+/** Outcome and update label names come from the pin, rather than a second policy. */
+export async function reviewPolicy(repoRoot) {
+  const { dir } = requirePin(repoRoot)
+  const policy = await import(pathToFileURL(join(dir, "scripts/security-baseline-policy.mjs")).href)
+  const approval = readFileSync(join(dir, "scripts/approve-plugin-update.mjs"), "utf8")
+  const updateLabel = approval.match(/for \(const required of \["([^"]+)"/)?.[1]
+  if (!updateLabel) throw new Error("cannot read the update issue label from the pin")
+  const manual = policy.currentSecurityBaselinePolicy.maintainerVerificationOutcome
+  return { automated: policy.securityBaselineOutcome([], []), manual, updateLabel, reviewLabel: `security-${manual}` }
+}
+
+/** The same discovery as watch --all; no credential or incomplete reads are not zero issues. */
+export async function openIssuesForRepository({ repoRoot, repository, offline = false, github = {} }) {
+  if (offline) return { count: null, reason: "not checked (--offline)" }
+  if (!(github.token || token)()) return { count: null, reason: "not checked: no GitHub credential" }
+  try {
+    const discovery = await discoverWatchIssues({ github })
+    const { dir } = requirePin(repoRoot)
+    let count = 0
+    let next = 0
+    async function worker() {
+      while (next < discovery.issues.length) {
+        const target = parseIssueUrl(discovery.issues[next++].url)
+        const subject = await (github.issue || issue)(target.owner, target.repository, target.number)
+        const parsed = await repositoryFor(dir, subject)
+        if (!parsed.url) throw new Error(`repository unknown on issue #${target.number}: ${parsed.error}`)
+        if (repositorySlug(parsed.url) === repositorySlug(repository)) count += 1
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(4, discovery.issues.length) }, worker))
+    return { count, reason: `watch --all discovery: ${count} open issue(s) for this repository` }
+  } catch (error) {
+    return { count: null, reason: `not checked (${error.code || "issue-discovery-unavailable"}): ${error.message}` }
+  }
+}
+
+export function reviewCostVerdict({ baseline, policy, openIssues = { count: null, reason: "not checked" }, why }) {
+  const capabilities = [...(baseline?.capabilities || [])]
+  const manual = baseline?.outcome === policy.manual
+  const automated = baseline?.outcome === policy.automated
+  const outcome = manual ? openIssues.count > 0 ? "manual queue, again" : "manual queue" : automated ? "automated" : null
+  const detail = manual
+    ? `${outcome}: capabilities ${capabilities.join(", ") || "none"}. Every update of this plugin, including a docs-only one, lands in the manual queue.${openIssues.count > 0 ? ` You already have ${openIssues.count} open issue(s) for this repository.` : ""}`
+    : automated ? "automated: this update will not need a human for the security baseline." : "not checked: baseline.preflight has no passed or review-required outcome"
+  return {
+    reviewCost: { outcome, capabilities, openIssuesForRepository: openIssues.count, reason: `${detail} ${openIssues.reason}` },
+    check: {
+      id: "review.cost", source: "omakit", severity: "advisory", verdict: manual ? "fail" : automated ? "pass" : "unknown",
+      why, detail, paths: [],
+      remedy: manual && openIssues.count > 0 ? "consider batching: close or fold the open one before opening another" : null,
+    },
+  }
+}
+
+/** A rename must be documentation at both ends; an empty diff is not a docs-only update. */
+export function documentationPath(path) {
+  return typeof path === "string" && !path.split("/").some((part) => part === "..") &&
+    (/^docs\//i.test(path) || /\.md$/i.test(path) || /(?:^|\/)LICENSE$/i.test(path) || /\.(?:png|jpe?g|gif|webp|svg|ico|avif|bmp|tiff?)$/i.test(path))
+}
+
+export function docsOnlyFiles(files) {
+  return Array.isArray(files) && files.length > 0 && files.every((file) =>
+    documentationPath(file.filename) && (!file.previous_filename || documentationPath(file.previous_filename)))
+}
+
+/** Select a dated validation record, never a parent guessed from Git history. */
+export function previousValidatedCommit(registry, report, catalog = null) {
+  if (!repositorySlug(report.plugin.repository)) return null
+  const sources = Array.isArray(registry?.sources) ? registry.sources : Object.values(registry?.sources || {})
+  const source = sources.find((entry) => repositorySlug(entry.repo) === repositorySlug(report.plugin.repository))
+  if (!report.validated?.commit) return null
+  const target = report.validated.commit
+  const checkedAt = Date.parse(report.validated.checkedAt)
+  const candidates = [...(Array.isArray(source?.listingValidationHistory) ? source.listingValidationHistory : []), {
+    commit: source?.listingValidatedCommit, validatedAt: source?.listingValidatedAt,
+  }, { commit: report.previousValidated?.commit, validatedAt: report.previousValidated?.checkedAt }]
+  // The catalog also records successful upstream validation before an update
+  // is promoted to the listing. This is validation evidence, not branch HEAD.
+  for (const plugin of Array.isArray(catalog?.plugins) ? catalog.plugins : []) {
+    if (repositorySlug(plugin.repo) === repositorySlug(report.plugin.repository)) {
+      candidates.push({ commit: plugin.upstreamValidatedCommit, validatedAt: plugin.upstreamValidatedAt })
+    }
+  }
+  return candidates.filter((entry) => /^[a-f0-9]{40}$/i.test(entry.commit || "") && entry.commit.toLowerCase() !== target.toLowerCase() &&
+    Number.isFinite(Date.parse(entry.validatedAt)) && Date.parse(entry.validatedAt) <= checkedAt)
+    .sort((a, b) => Date.parse(a.validatedAt) - Date.parse(b.validatedAt)).at(-1)?.commit.toLowerCase() || null
+}
+
+export async function validatedDocumentationDiff({ report, registry, catalog, registryReason = null, compare = compareCommits }) {
+  const previous = previousValidatedCommit(registry, report, catalog)
+  if (!previous) return { previousCommit: null, validatedCommit: report.validated?.commit || null, docsOnly: null, files: null, source: null, reason: registryReason || "previous validated commit unknown in the marketplace registry" }
+  try {
+    const diff = await compare(report.plugin.repository, previous, report.validated.commit)
+    return { previousCommit: previous, validatedCommit: report.validated.commit, docsOnly: docsOnlyFiles(diff.files), files: diff.files.length, source: diff.url, reason: null }
+  } catch (error) {
+    return { previousCommit: previous, validatedCommit: report.validated.commit, docsOnly: null, files: null, source: null, reason: `${error.code || "compare-unavailable"}: ${error.message}` }
+  }
+}

package/tools/marketplace/style.mjs

@@ -115,9 +115,8 @@ export function code(role) {
 // --- geometry ---------------------------------------------------------------
 
 /**
- * The width everything is composed for. Eighty columns is the contract: a
- * check's why-paragraph, a remedy, a refusal and the help all wrap inside it,
- * and tests/unit/style.test.mjs renders every report and measures. The one
+ * The stable width for pipes and files. Terminals use their current column
+ * count, up to MAX_COLUMNS so wide windows still have readable prose. The one
  * thing exempt is the marketplace's own baseline report, which is printed
  * verbatim because rewrapping somebody else's attestation would be editing it.
  *
@@ -125,6 +124,23 @@ export function code(role) {
  * `overflows` below is the measurement, and it is the one both test files use.
  */
 export const COLUMNS = 80
+export const MAX_COLUMNS = 120
+
+let compositionStream = null
+
+/** Resolve at rendering time, so a resized terminal's next output uses its new width. */
+export function outputColumns(stream = compositionStream || process.stdout) {
+  return stream?.isTTY && Number.isFinite(stream.columns) && stream.columns >= 1
+    ? Math.min(MAX_COLUMNS, Math.floor(stream.columns))
+    : COLUMNS
+}
+
+/** Scope synchronous composition to its destination, including files and stderr. */
+export function withOutputStream(stream, render) {
+  const previous = compositionStream
+  compositionStream = stream
+  try { return render() } finally { compositionStream = previous }
+}
 
 /**
  * The indent scale, in columns. Three stops, and every line in the tool starts
@@ -327,7 +343,7 @@ export function overflows(line, total = COLUMNS) {
 // --- composition ------------------------------------------------------------
 
 /**
- * Wrap prose to the contract width, and paint it.
+ * Wrap prose to the destination width, and paint it.
  *
  * `indent` is the column the text starts in and is part of the width, which is
  * the bug the earlier version had: it wrapped at 78 and then indented by 7, and
@@ -346,7 +362,7 @@ export function overflows(line, total = COLUMNS) {
  * @param {(name: string, text: string) => string} [c]
  * @returns {string[]} lines, indented and painted
  */
-export function wrap(text, { indent = 0, width: total = COLUMNS, first = indent } = {}, c = styler(false)) {
+export function wrap(text, { indent = 0, width: total = outputColumns(), first = indent } = {}, c = styler(false)) {
   // A word is a run of non-spaces, or a backticked span with whatever
   // punctuation clings to it: "(`omakit pin`)." is one word.
   const words = String(text).match(/[^\s`]*`[^`]*`[^\s`]*|\S+/g) || []
@@ -422,7 +438,7 @@ export function continuation(value, c) {
  * under itself. There is exactly one of these under any failure, and it is the
  * only line in the tool that starts with an arrow, so it can be found by shape.
  */
-export function action(text, c, { indent = GUTTER, width: total = COLUMNS } = {}) {
+export function action(text, c, { indent = GUTTER, width: total = outputColumns() } = {}) {
   // Painted after wrapping, and all of it cyan: the whole line is the thing
   // to do, so a backticked word inside it has nothing to stand out from.
   const lines = wrap(text, { indent: indent + 2, width: total })
@@ -449,11 +465,11 @@ export function labelled(label, text, c, { indent = GUTTER } = {}) {
  * grey. It is the same shape the wordmark uses (the name, then its rule), so a
  * section of a report and the front door of the tool are drawn by one idea.
  */
-export function section(title, c, { width: total = COLUMNS } = {}) {
+export function section(title, c, { width: total = outputColumns() } = {}) {
   return [c("heading", title), c("punctuation", DENSITY.floor.repeat(total))]
 }
 
 /** A rule with no heading, the same floor, for a wordmark or a block that names itself. */
-export function rule(c, { width: total = COLUMNS, tint = "punctuation" } = {}) {
+export function rule(c, { width: total = outputColumns(), tint = "punctuation" } = {}) {
   return c(tint, DENSITY.floor.repeat(total))
 }

package/tools/marketplace/submit.mjs

@@ -23,6 +23,7 @@ import { renderIssue, verifyAgainstOfficialParser } from "./issue.mjs"
 import { defaultBranchHead } from "./github.mjs"
 import { REFRESH_ACTION } from "./watch.mjs"
 import { omakitCacheDir } from "./paths.mjs"
+import { openIssuesForRepository, reviewCostVerdict, reviewPolicy } from "./review-cost.mjs"
 
 /**
  * One arrow per cause, in this order, so a person fixes the thing that is
@@ -135,6 +136,7 @@ export function reproduceCommand({ target, category, tags, pluginName, notes, su
  * @param {{ repoRoot: string, target: string, category?: string, tags?: string|string[],
  *           notes?: string, suggestedTag?: string, pluginName?: string,
  *           allowDirty?: boolean, offline?: boolean,
+ *           github?: object,
  *           readRegistry?: typeof liveRegistry,
  *           chooser?: (question: { contract: object, defaults: object, missing: string[] }) => Promise<{ category?: string, tags?: string[] }> }} options
  *   `readRegistry` is injectable for tests; the default reads the marketplace's
@@ -404,7 +406,7 @@ export async function submitPreflight(options) {
   if (!options.offline && subject.repository.url) {
     phase("reading the repository's default-branch HEAD")
     try {
-      head = await defaultBranchHead(subject.repository.url)
+      head = await (options.github?.defaultBranchHead || defaultBranchHead)(subject.repository.url)
     } catch (error) {
       headError = { code: error.code || "head-unreadable", message: error.message }
     }
@@ -412,9 +414,14 @@ export async function submitPreflight(options) {
   const validationMatches = head ? head.commit === subject.commit.toLowerCase() : null
   checks.push(check("submission.validation-commit", {
     source: "omakit",
-    why: "The marketplace validates the default-branch HEAD it resolves when the issue is opened or edited, not the commit checked here. 73% of the 464 submissions parked in the author's court have a HEAD ahead of their validated commit, so a preflight against a commit that is not the pushed HEAD describes a tree nobody will review. Not a marketplace rule; an Omakit refusal to report on the wrong tree.",
+    why: "The marketplace validates the default-branch HEAD it resolves when the issue is opened or edited, not the commit checked here. M6 on 2026-09-15 found 326/519 readable author-fixes comparisons stale (62.8%), with 64 of 583 issues unknown, so a preflight against a commit that is not the pushed HEAD describes a tree nobody will review. Not a marketplace rule; an Omakit refusal to report on the wrong tree.",
     severity: options.offline ? "advisory" : "blocking",
     skipped: options.offline === true,
+    // No origin, no URL to read a HEAD from: the check waits on the one that
+    // says so. Measured on 0.4.1: it failed as a second root cause with
+    // "could not read the default-branch HEAD (unknown): " for a read that
+    // was never attempted.
+    waitedOn: [!options.offline && !subject.repository.url && "submission.repository-url"],
     verdict: validationMatches === true,
     detail: options.offline
       ? `not checked (--offline). Local commit ${subject.commit}.`
@@ -461,6 +468,14 @@ export async function submitPreflight(options) {
         : null,
   }))
 
+  const policy = await reviewPolicy(repoRoot)
+  const review = reviewCostVerdict({ baseline: consequence, policy,
+    openIssues: consequence?.outcome === policy.manual ? await openIssuesForRepository({ repoRoot, repository: subject.repository.url,
+      offline: options.offline === true, github: options.github }) : { count: null, reason: consequence?.outcome === policy.automated ? "open issue count not checked: automated baseline" : preflight.skipReason || preflight.refusal?.message || "baseline outcome needs findings resolved" },
+    why: `MEASUREMENTS.md M4: ${figure(figures.outcomes[policy.manual] || 0)} of ${figure(figures.withBaseline)} recorded listing baselines required review at the pin. M9: on 2026-09-15, 140 of 307 open update issues carried the manual-review label; 4 of 139 compared validated diffs were docs-only, with 1 unavailable. The baseline scans the whole snapshot, not the update diff, so unchanged capabilities also require another review. Sources and exact marketplace HEAD are recorded in MEASUREMENTS.md.`,
+  })
+  checks.push(review.check)
+
   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")
@@ -511,6 +526,7 @@ export async function submitPreflight(options) {
       offline: options.offline === true,
     }),
     checks,
+    reviewCost: review.reviewCost,
     outcome,
     ready,
     listing,

package/tools/marketplace/usage.mjs

@@ -7,7 +7,7 @@
 
 import { UNAUTHENTICATED_LIMIT } from "./github.mjs"
 import { MARKETPLACE_PIN } from "./pin.mjs"
-import { colourEnabled, paintProse, STEP, styler } from "./style.mjs"
+import { colourEnabled, paintProse, STEP, styler, withOutputStream, wrap } from "./style.mjs"
 
 /**
  * "Safe" means one thing, everywhere it appears: this runs on your own
@@ -208,16 +208,40 @@ export function paintSignature(signature, c) {
  *
  * @param {{ colour?: boolean, heading?: boolean }} [options]
  */
-export function renderSummary({ colour = colourEnabled(), heading = true } = {}) {
-  const c = styler(colour)
-  const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
-  for (const command of COMMANDS) {
-    out.push(`${INDENT}${paintSignature([].concat(command.signature)[0], c)}`)
+function commandSignatures(command) {
+  const signatures = []
+  for (const line of [].concat(command.signature)) {
+    if (line.startsWith("omakit ")) signatures.push(line)
+    else signatures[signatures.length - 1] += ` ${line}`
   }
-  out.push("")
-  out.push(`${INDENT}${paintProse("`omakit help` is the same list with what each command does, and", c)}`)
-  out.push(`${INDENT}${paintProse("what it reads. `omakit setup` is the one to run first.", c)}`)
-  return `${out.join("\n")}\n`
+  return signatures
+}
+
+function signatureLines(signature, c) {
+  // A placeholder or bracketed optional argument stays whole, like the
+  // backticked typeable spans used by the shared wrapper.
+  const grouped = signature.replace(/\[[^\]]+\]|<[^>]+>(?:@<[^>]+>)?/g, (part) => `\`${part}\``)
+  return wrap(grouped, { indent: STEP * 3, first: STEP }).map((line) => paintSignature(line, c))
+}
+
+export function renderSummary({ stream = process.stdout, colour = colourEnabled(stream), heading = true } = {}) {
+  return withOutputStream(stream, () => {
+    const c = styler(colour)
+    const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+    if (stream.isTTY && heading) out.splice(0, 1, ...wrap(out[0]))
+    for (const command of COMMANDS) {
+      if (stream.isTTY) out.push(...signatureLines([].concat(command.signature)[0], c))
+      else out.push(`${INDENT}${paintSignature([].concat(command.signature)[0], c)}`)
+    }
+    out.push("")
+    if (stream.isTTY) {
+      out.push(...wrap("`omakit help` is the same list with what each command does, and what it reads. `omakit setup` is the one to run first.", { indent: STEP }, c))
+    } else {
+      out.push(`${INDENT}${paintProse("`omakit help` is the same list with what each command does, and", c)}`)
+      out.push(`${INDENT}${paintProse("what it reads. `omakit setup` is the one to run first.", c)}`)
+    }
+    return `${out.join("\n")}\n`
+  })
 }
 
 /**
@@ -225,23 +249,29 @@ export function renderSummary({ colour = colourEnabled(), heading = true } = {})
  *   when the line above has already named the tool, as under an unknown
  *   command, so the same sentence is not printed twice.
  */
-export function renderUsage({ colour = colourEnabled(), heading = true } = {}) {
-  const c = styler(colour)
-  const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+export function renderUsage({ stream = process.stdout, colour = colourEnabled(stream), heading = true } = {}) {
+  return withOutputStream(stream, () => {
+    const c = styler(colour)
+    const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+    if (stream.isTTY && heading) out.splice(0, 1, ...wrap(out[0]))
 
-  for (const command of COMMANDS) {
-    for (const line of [].concat(command.signature)) {
-      out.push(`${INDENT}${paintSignature(line, c)}`)
-    }
-    for (const line of command.lines) {
-      out.push(`${DESCRIPTION}${paintProse(line, c)}`)
+    for (const command of COMMANDS) {
+      if (stream.isTTY) {
+        for (const signature of commandSignatures(command)) out.push(...signatureLines(signature, c))
+        out.push(...wrap(command.lines.join(" "), { indent: STEP * 3 }, c))
+      } else {
+        for (const line of [].concat(command.signature)) out.push(`${INDENT}${paintSignature(line, c)}`)
+        for (const line of command.lines) out.push(`${DESCRIPTION}${paintProse(line, c)}`)
+      }
+      out.push("")
     }
-    out.push("")
-  }
 
-  out.push(`${INDENT}${paintSignature(TARGET_NOTE, c)}`)
-  out.push("")
-  out.push(c("heading", "GitHub access:"))
-  for (const line of AUTHENTICATION) out.push(`${INDENT}${paintProse(line, c)}`)
-  return `${out.join("\n")}\n`
+    if (stream.isTTY) out.push(...signatureLines(TARGET_NOTE, c))
+    else out.push(`${INDENT}${paintSignature(TARGET_NOTE, c)}`)
+    out.push("")
+    out.push(c("heading", "GitHub access:"))
+    if (stream.isTTY) out.push(...wrap(AUTHENTICATION.join(" "), { indent: STEP }, c))
+    else for (const line of AUTHENTICATION) out.push(`${INDENT}${paintProse(line, c)}`)
+    return `${out.join("\n")}\n`
+  })
 }

package/tools/marketplace/watch.mjs

@@ -9,19 +9,11 @@
 // compares branch HEADs only for repositories that are already listed. So
 // pushing a fix does nothing, and commenting "fixed in abc123" does nothing.
 //
-// Measured reason (docs/MEASUREMENTS.md M6): of the 464 submissions parked in
-// the author's court, 73% have a default-branch HEAD ahead of the validated
-// commit. 47% pushed after the maintainer's review without the marketplace ever
-// seeing it, and 82% of those authors also commented, so they are engaged and
-// stuck rather than gone. Of 13 open submissions inspected with no labels left,
-// 9 had passed validation and passed the automated security baseline with zero
-// findings and were blocked solely because their validated commit had fallen
-// behind while they waited. 46% of the maintainer's own requests for a fresh validation never
-// produced one; in the parked group 77% never did. The instruction that would
-// fix this appears 22 times in the failure path of
-// `scripts/submission-feedback.mjs` and zero times in the success path of
-// `scripts/validate-submission.mjs`, which is the path 97 of 100 parked
-// submissions took.
+// Measured reason (docs/MEASUREMENTS.md M6), 2026-09-15: 326 of 519 readable
+// author-fixes comparisons were stale (62.8%), with 64 of 583 issues unknown.
+// The original 2026-09-12 research sampled 100 of a 464-issue queue: 68 of
+// 93 readable pairs were stale (73.1%). It did not measure every queue item.
+// Editing the issue body is the action the pinned workflow observes.
 //
 // This command reads. It never edits the issue, never comments, never labels.
 // The action it names is the author's to take.
@@ -30,6 +22,8 @@ import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
 import { authenticatedUser, repositoryIssues, defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
+import { liveRegistry } from "./registry.mjs"
+import { reviewPolicy, validatedDocumentationDiff } from "./review-cost.mjs"
 
 export class WatchError extends Error {
   constructor(code, message) {
@@ -77,8 +71,11 @@ export async function discoverWatchIssues({ user, github = {}, onPhase = () => {
 }
 
 /** A batch keeps independent read failures visible and shares repository HEAD reads. */
-export async function validationWatchAll({ repoRoot, discovery, github = {}, onPhase = () => {} }) {
+export async function validationWatchAll({ repoRoot, discovery, github = {}, readRegistry = liveRegistry, onPhase = () => {} }) {
   if (discovery.issues.length) requirePin(repoRoot)
+  const policy = discovery.issues.length ? await reviewPolicy(repoRoot) : null
+  let registry = null
+  const reviewCostSummary = { pluginUpdates: 0, manualQueue: 0, docsOnly: 0, compared: 0, skipped: [] }
   const heads = new Map()
   const readHead = github.defaultBranchHead || defaultBranchHead
   const shared = { ...github, defaultBranchHead: (url) => {
@@ -102,7 +99,38 @@ export async function validationWatchAll({ repoRoot, discovery, github = {}, onP
   await Promise.all(Array.from({ length: Math.min(4, discovery.issues.length) }, worker))
   const summary = { total: results.length, current: 0, stale: 0, unknown: 0 }
   for (const result of results) summary[result.report?.verdict.state || "unknown"] += 1
-  return { mode: "all", account: discovery.account, marketplace: discovery.marketplace, summary, issues: results }
+  // M9: count labels on the listed issues, then compare only updates in the manual queue.
+  const manual = results.filter((row) => {
+    const labels = row.report?.read.labels || row.issue.labels
+    if (!labels.includes(policy?.updateLabel)) return false
+    reviewCostSummary.pluginUpdates += 1
+    return labels.includes(policy.reviewLabel)
+  })
+  reviewCostSummary.manualQueue = manual.length
+  if (manual.length) {
+    onPhase("reading the previous validated marketplace snapshots")
+    try { registry = await readRegistry({ repoRoot }) } catch (error) { registry = { reason: error.message } }
+  }
+  let compareNext = 0
+  async function compareWorker() {
+    while (compareNext < manual.length) {
+      const row = manual[compareNext++]
+      const diff = row.report
+        ? await validatedDocumentationDiff({ report: row.report, registry: registry?.source === "head" ? registry.registry : null,
+          catalog: registry?.source === "head" ? registry.catalog : null,
+          registryReason: registry?.source === "head" ? null : `previous validated commit unknown: live registry unavailable (${registry?.reason || "unknown"})`, compare: github.compareCommits })
+        : { docsOnly: null, reason: `issue unreadable: ${row.error?.message || "unknown"}` }
+      row.documentationDiff = diff
+      if (diff.docsOnly === null) reviewCostSummary.skipped.push({ issue: row.issue.number, reason: diff.reason })
+      else {
+        reviewCostSummary.compared += 1
+        if (diff.docsOnly) reviewCostSummary.docsOnly += 1
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, manual.length) }, compareWorker))
+  reviewCostSummary.skipped.sort((a, b) => a.issue - b.issue)
+  return { mode: "all", account: discovery.account, marketplace: discovery.marketplace, summary, reviewCostSummary, issues: results }
 }
 
 // The one action that re-runs validation, in the register the marketplace itself
@@ -133,7 +161,7 @@ async function loadVerification(pinDir) {
  * happens to recognise. So each form is read by the parser the marketplace
  * itself uses for it, and the issue says which one it is.
  */
-async function repositoryFor(pinDir, subject) {
+export async function repositoryFor(pinDir, subject) {
   const submission = await loadSubmission(pinDir)
   const verification = await loadVerification(pinDir)
   const title = String(subject.title || "")
@@ -221,11 +249,29 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase, github = {}
     baselineError = { code: error.code || "baseline-unreadable", message: error.message }
   }
   const fallback = validated ? null : validationCommentCommit(comments)
+  let previousValidated = null
+  if (validated) {
+    // Revalidation on an existing issue may precede the latest marker. Ignore
+    // repeated attestations of the same commit, not a different validated tree.
+    for (const comment of [...comments].reverse()) {
+      try {
+        const marker = record.findLatestSecurityBaseline([comment])
+        if (marker && marker.commitSha !== validated.commit && Date.parse(marker.checkedAt) <= Date.parse(validated.checkedAt)) {
+          previousValidated = { commit: marker.commitSha, checkedAt: marker.checkedAt, source: "security-baseline-marker" }
+          break
+        }
+      } catch { /* An incomplete run is not a previously validated commit. */ }
+    }
+  }
 
   const labels = (subject.labels || []).map((label) => (typeof label === "string" ? label : label?.name)).filter(Boolean)
   const authorComments = comments.filter((comment) => comment?.user?.login === subject.user?.login)
+  // The discussion is a person's: the marketplace's own bot and any other
+  // automation (GitHub marks an app's account `type: "Bot"`, and names it
+  // `<app>[bot]`) is neither a reviewer nor the last human review.
+  const isBot = (user) => user?.type === "Bot" || /\[bot\]$/i.test(String(user?.login || ""))
   const maintainerComments = comments.filter(
-    (comment) => comment?.user?.login && comment.user.login !== subject.user?.login && comment.user.login !== "github-actions[bot]",
+    (comment) => comment?.user?.login && comment.user.login !== subject.user?.login && !isBot(comment.user),
   )
 
   let head = null
@@ -267,6 +313,7 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase, github = {}
     },
     plugin: { repository: repositoryUrl, repositoryError, form: issueKind },
     validated,
+    previousValidated,
     validationCommentFallback: fallback,
     baselineError,
     head,