omakit 0.2.2 → 0.4.0

package/README.md

@@ -25,15 +25,21 @@ See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements a
 | --- | --- |
 | [`omakit setup`](docs/COMMANDS.md) | The environment, the pin, tab completion, and what to try first. |
 | [`omakit submit <plugin-repo>`](docs/SUBMIT.md) | Every check, the issue title and body; asks for a category and tags at a terminal. |
-| [`omakit watch <issue-url>`](docs/VALIDATION_WATCH.md) | The commit the marketplace validated, against the plugin's current HEAD. |
+| [`omakit watch [<issue-url>]`](docs/VALIDATION_WATCH.md) | Pick your marketplace issues, list them, or check all with `--all`. |
 | [`omakit verify <plugin-repo>`](docs/COMMANDS.md) | The official security baseline over the local transport; `--json` for the document. |
 | [`omakit parity`](docs/COMMANDS.md) | The baseline over GitHub versus the local transport, on real listings; writes the evidence. |
+| [`omakit audit [<plugin>]`](docs/AUDIT.md) | Installed third-party commits against the exact commits the marketplace validated. |
 | [`omakit weigh <plugin>`](docs/WEIGH.md) | What a plugin weighs on the shell, measured by restarting it without and with the plugin; asks first. |
 | [`omakit doctor`](docs/COMMANDS.md) | What is installed, what is pinned, and what has moved. |
 | [`omakit pin`](docs/COMMANDS.md) | What setup does for the pin, on its own. |
 | [`omakit upgrade`](docs/COMMANDS.md) | Updates omakit through its own installer: npm, or a fast-forward. |
 | [`omakit help --agent`](docs/COMMANDS.md) | The operating instructions, for the agent running this. |
 
+Normal terminal use also checks for a newer npm release at most once daily
+and shows the upgrade command. It installs nothing automatically; scripts
+and JSON stay quiet. `DISABLE_UPDATE_NOTIFIER=1` disables the notice, and
+`omakit doctor` checks explicitly. [Update behaviour](docs/INSTALL.md#updating).
+
 ### `submit`
 
 ```bash
@@ -50,10 +56,15 @@ Read more: [docs/SUBMIT.md](docs/SUBMIT.md).
 
 ```bash
 omakit watch <submission-issue-url>
+omakit watch --all
+omakit watch --list
+omakit watch                 # choose one or several issues at a terminal
 ```
 
 It decides whether the marketplace validated the plugin's current commit; [73% of parked submissions have a HEAD the marketplace never saw](docs/MEASUREMENTS.md).
 
+Account-wide discovery uses your signed-in `gh` account and reads your open marketplace issues. `--user <login>` reads another public account. Batch output includes baseline results, labels and the latest human discussion; `current` compares commits and does not imply approval or publication. Each command takes one snapshot and posts nothing.
+
 ![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
 
 Read more: [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md).
@@ -95,6 +106,7 @@ Committed evidence records a digest of each side rather than the results themsel
 | [docs/INSTALL.md](docs/INSTALL.md) | install details, PATH, requirements, upgrading, and what Socket reports and why |
 | [docs/HOW.md](docs/HOW.md) | what omakit is doing, why it uses Node, the baseline and check labels |
 | [docs/COMMANDS.md](docs/COMMANDS.md) | command details, authentication and network behaviour |
+| [docs/AUDIT.md](docs/AUDIT.md) | installed plugin drift against marketplace-validated commits, with JSON origins |
 | [docs/SUBMIT.md](docs/SUBMIT.md) | every check and what it decides |
 | [docs/WEIGH.md](docs/WEIGH.md) | what `weigh` measures, the noise floor, the `shell.json` mutation and its restore, and the JSON contract |
 | [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md) | the validation watch: what the marketplace validated, and what moves it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/skills/omarchy-plugin-audit/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: omarchy-plugin-audit
+description: Compare installed Omarchy Quattro plugin commits with the exact commits the marketplace validated. Use before touching an installed third-party plugin, before enabling or updating one, or when asked whether installed plugins match marketplace review. Read-only.
+---
+
+# Audit installed plugin commits
+
+Run `omakit audit` before touching an installed third-party plugin. Run
+`omakit audit <plugin-id-or-dir>` when only one installed plugin is in scope.
+The command reads the shell's installed list, the marketplace catalog and local
+Git facts. It changes nothing.
+
+Read the primary state first:
+
+- `validated` means installed HEAD is one of the commits the marketplace
+  records as validated.
+- `ahead` means a validated commit is an ancestor, but HEAD contains later
+  commits the marketplace did not validate.
+- `diverged` means installed history does not descend from a validated commit,
+  or its origin is not the listed repository. A validated object missing from
+  local history is diverged, with the clone's shallow status stated.
+- `unverified` means the listing records no validated commit. Its status is stated.
+- `unlisted` means neither plugin id nor origin identifies a listing.
+- `unknown` means Git or the source directory could not answer. Keep the error.
+
+Then report every stacking flag: `modified`, `disabled`, and `upstream moved`.
+Do not collapse a flag into the primary state. First-party plugins are counted
+and excluded because they ship with the shell.
+
+Use `--json` when another tool needs the document. Every figure carries its
+origin. Use `--offline` when the live catalog must not be read; the header will
+name the pin. `--drift` is a view filter, not a different measurement.
+
+An `ahead` or `diverged` report prints the exact checkout command for the
+validated commit and names the marketplace form for validating a newer one.
+Never run that checkout command without the person's explicit request. Never
+replace it with `omarchy plugin update`; update moves to mutable HEAD and does
+not establish marketplace validation.
+
+`AUDITED`, exit 0, means every audited row is validated, or there was nothing
+third-party to audit. `DRIFT`, exit 1, means drift or an unknown answer.
+Exit 2 means the invocation was refused. `NOT AUDITED` because the shell or
+catalog did not answer is a
+result to report, not a reason to substitute a directory scan.

package/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -27,6 +27,8 @@ push came after a review comment had also commented: engaged, and stuck.
 
 ```bash
 omakit watch https://github.com/omacom/omarchy-plugin-marketplace/issues/<number>
+omakit watch --all --json
+omakit watch --list --json
 ```
 
 If `omakit` is not installed: `npm install --global omakit` (Omarchy ships Node
@@ -35,6 +37,10 @@ the install, `"$(npm prefix --global)/bin/omakit" setup` prints the one line
 that puts npm's bin on PATH. `omakit upgrade` keeps it current through npm.
 Add `--json` for a machine-readable result.
 
+Use `--all --json` to discover and check every open marketplace issue authored by the signed-in `gh` account. `--list --json` discovers issue URLs without reading every plugin; use an individual URL for focused follow-up. `--user <login>` selects an explicit public author. A bare `omakit watch` opens a numbered picker only at a terminal; an agent must pass a URL, `--all` or `--list` and never wait on keyboard input.
+
+Inspect every batch row, including read errors and unknown results; a successful row cannot stand in for a failed one. `current` only says the commit matches HEAD. Read the baseline outcome, labels and latest discussion to understand outstanding work; never equate it with approval, publication or restored catalog verification. A run is a single read-only snapshot, not a background monitor.
+
 Read-only. It does not comment, label, or edit anything, and it cannot. It reads
 the default branch through the REST API when a credential is available, taking
 it from the operator's `gh` login (which itself honours `GH_TOKEN` and

package/tools/audit/audit.mjs

@@ -0,0 +1,223 @@
+// Compare installed third-party checkouts with commits recorded by the live
+// marketplace catalog. Nothing here fetches or changes a checkout.
+
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { newerCommitChoice } from "../marketplace/form.mjs"
+import { liveRegistry, sameRepository } from "../marketplace/registry.mjs"
+import { installedPlugins } from "../weigh/list.mjs"
+import { ancestorOf, commitsAfter, hasCommit, isShallow, readCheckout } from "./git.mjs"
+
+export class AuditError extends Error {
+  constructor(code, message, remedy = null) {
+    super(message)
+    this.name = "AuditError"
+    this.code = code
+    this.remedy = remedy
+  }
+}
+
+const text = (value) => (typeof value === "string" && value ? value : null)
+const lower = (value) => text(value)?.toLowerCase() || null
+const figure = (value, origin) => (value === null || value === undefined ? null : { value, origin })
+const catalogFigure = (listing, name) => figure(text(listing?.[name]), `site/catalog.json ${name}`)
+const short = (value) => value.slice(0, 8)
+const ROW_ORDER = ["diverged", "ahead", "modified", "unverified", "unlisted", "unknown", "validated"]
+const rowRank = (row) => ROW_ORDER.indexOf(["diverged", "ahead"].includes(row.state) ? row.state : row.flags.includes("modified") ? "modified" : row.state)
+
+function targetId(target) {
+  if (!target || !existsSync(target)) return target || null
+  try {
+    return text(JSON.parse(readFileSync(resolve(target, "manifest.json"), "utf8"))?.id)
+  } catch {
+    return null
+  }
+}
+
+function chooseListing(plugin, checkout, listings) {
+  const byId = listings.find((entry) => entry?.id === plugin.id) || null
+  const byOrigin = listings.find((entry) => sameRepository(entry?.repo, checkout.repository)) || null
+  if (byId && byOrigin && byId !== byOrigin) {
+    return { listing: null, conflict: `manifest id matches ${byId.id}, but origin matches ${byOrigin.id}; neither listing was used` }
+  }
+  return { listing: byId || byOrigin, conflict: null }
+}
+
+function validatedFigures(listing) {
+  const figures = []
+  const add = (prefix) => {
+    const commit = lower(listing?.[`${prefix}ValidatedCommit`])
+    if (!commit || figures.some((entry) => entry.commit.value === commit)) return
+    figures.push({
+      kind: prefix,
+      commit: figure(commit, `site/catalog.json ${prefix}ValidatedCommit`),
+      date: catalogFigure(listing, `${prefix}ValidatedAt`),
+      branch: catalogFigure(listing, prefix === "listing" ? "listingValidatedBranch" : "upstreamObservedBranch"),
+    })
+  }
+  add("upstream")
+  add("listing")
+  return figures
+}
+
+function rowFact(plugin, checkout, listing, conflict, git, env) {
+  const flags = []
+  if (checkout.status) flags.push("modified")
+  if (plugin.enabled !== true) flags.push("disabled")
+  const validated = validatedFigures(listing)
+  const observed = lower(listing?.upstreamObservedCommit)
+  if (observed && observed !== checkout.commit && !validated.some((entry) => entry.commit.value === observed)) flags.push("upstream moved")
+
+  const common = {
+    id: plugin.id,
+    flags,
+    installed: {
+      commit: figure(checkout.commit, "git rev-parse HEAD"),
+      enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled"),
+      modified: figure(Boolean(checkout.status), "git status --porcelain"),
+      repository: figure(checkout.repository, "git remote get-url origin"),
+    },
+    validated,
+    upstream: {
+      observedCommit: catalogFigure(listing, "upstreamObservedCommit"),
+      observedBranch: catalogFigure(listing, "upstreamObservedBranch"),
+      checkedAt: catalogFigure(listing, "upstreamCheckedAt"),
+      checkStatus: catalogFigure(listing, "upstreamCheckStatus"),
+    },
+    sourceDir: plugin.sourceDir,
+    listing: listing ? { id: listing.id, repository: listing.repo } : null,
+  }
+
+  if (!listing) return { ...common, state: "unlisted", fact: conflict || "manifest id and origin match no marketplace listing", aheadBy: null, matchedValidated: null }
+  if (validated.some((entry) => entry.commit.value === checkout.commit)) {
+    const matched = validated.find((entry) => entry.commit.value === checkout.commit)
+    return { ...common, state: "validated", fact: `validated ${short(matched.commit.value)} on ${matched.date?.value || "an unrecorded date"}`, aheadBy: null, matchedValidated: matched }
+  }
+  if (!validated.length) {
+    return { ...common, state: "unverified", fact: `listed with verificationStatus ${listing.verificationStatus || "unrecorded"}, and no validated commit`, aheadBy: null, matchedValidated: null }
+  }
+  const missing = []
+  for (const candidate of validated) {
+    if (!git.hasCommit(plugin.sourceDir, candidate.commit.value, { env })) {
+      missing.push(candidate)
+      continue
+    }
+    if (git.ancestor(plugin.sourceDir, candidate.commit.value, { env })) {
+      const count = git.count(plugin.sourceDir, candidate.commit.value, { env })
+      return { ...common, state: "ahead", fact: `${count} commit${count === 1 ? "" : "s"} ahead of validated ${short(candidate.commit.value)} (${candidate.date?.value || "unrecorded date"}); HEAD ${short(checkout.commit)}`, aheadBy: figure(count, `git rev-list --count ${candidate.commit.value}..HEAD`), matchedValidated: candidate }
+    }
+  }
+  if (missing.length) {
+    const shallow = figure(git.shallow(plugin.sourceDir, { env }), "git rev-parse --is-shallow-repository")
+    return { ...common, state: "diverged", fact: `validated commit not in local history; shallow clone: ${shallow.value}`, shallow, aheadBy: null, matchedValidated: missing[0] }
+  }
+  const moved = sameRepository(checkout.repository, listing.repo)
+  return { ...common, state: "diverged", fact: moved ? "installed commit does not descend from a validated commit" : `origin does not match ${listing.repo}`, aheadBy: null, matchedValidated: validated[0] }
+}
+
+/**
+ * Audit the installed third-party plugin set, or one target from that set.
+ * All external readers are injectable so tests establish every state without
+ * touching the person's shell or plugin directories.
+ */
+export async function auditInstalled(options = {}) {
+  const env = options.env || process.env
+  const readers = {
+    installed: options.installed || ((args) => installedPlugins(args)),
+    registry: options.registry || ((args) => liveRegistry(args)),
+    checkout: options.checkout || ((dir, args) => readCheckout(dir, args)),
+    hasCommit: options.hasCommit || ((dir, sha, args) => hasCommit(dir, sha, args)),
+    shallow: options.shallow || ((dir, args) => isShallow(dir, args)),
+    ancestor: options.ancestor || ((dir, sha, args) => ancestorOf(dir, sha, args)),
+    count: options.count || ((dir, sha, args) => commitsAfter(dir, sha, args)),
+    route: options.route || ((args) => newerCommitChoice(args)),
+  }
+  let installed
+  try {
+    installed = readers.installed({ env })
+  } catch (error) {
+    throw new AuditError(error?.code || "shell-not-running", error?.message || String(error))
+  }
+  let live
+  try {
+    live = await readers.registry({ repoRoot: options.repoRoot, offline: options.offline })
+  } catch (error) {
+    throw new AuditError(error?.code || "marketplace-unavailable", error?.message || String(error), error?.remedy || "omakit pin")
+  }
+  const listings = Array.isArray(live.catalog?.plugins) ? live.catalog.plugins : null
+  if (!listings) throw new AuditError("catalog-unreadable", "the marketplace catalog has no plugins array", "omakit pin")
+
+  const wanted = targetId(options.target)
+  let selected = installed
+  if (options.target) {
+    const path = existsSync(options.target) ? resolve(options.target) : null
+    selected = installed.filter((plugin) => plugin.id === wanted || (path && plugin.sourceDir && resolve(plugin.sourceDir) === path))
+    if (!selected.length) throw new AuditError("plugin-not-installed", `${JSON.stringify(options.target)} is not an installed plugin`, "omakit audit")
+  }
+
+  let firstPartyCount = 0
+  const rows = []
+  for (const plugin of selected) {
+    const idListing = listings.find((entry) => entry?.id === plugin.id)
+    if (plugin.firstParty === true || idListing?.sourceType === "builtin") {
+      firstPartyCount += 1
+      continue
+    }
+    if (!plugin.sourceDir) {
+      rows.push({ id: plugin.id, state: "unknown", flags: plugin.enabled === true ? [] : ["disabled"], installed: { enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled") }, validated: [], upstream: {}, sourceDir: null, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: "omarchy-plugin-catalog records no source directory", error: "source directory unavailable", aheadBy: null, matchedValidated: null })
+      continue
+    }
+    let checkout
+    try {
+      checkout = readers.checkout(plugin.sourceDir, { env })
+    } catch (error) {
+      rows.push({ id: plugin.id, state: "unknown", flags: plugin.enabled === true ? [] : ["disabled"], installed: { enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled") }, validated: [], upstream: {}, sourceDir: plugin.sourceDir, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: `git failed: ${error.message}`, error: error.message, aheadBy: null, matchedValidated: null })
+      continue
+    }
+    try {
+      const { listing, conflict } = chooseListing(plugin, checkout, listings)
+      if (listing?.sourceType === "builtin") {
+        firstPartyCount += 1
+        continue
+      }
+      rows.push(rowFact(plugin, checkout, listing, conflict, readers, env))
+    } catch (error) {
+      rows.push({ id: plugin.id, state: "unknown", flags: [checkout.status ? "modified" : null, plugin.enabled === true ? null : "disabled"].filter(Boolean), installed: { commit: figure(checkout.commit, "git rev-parse HEAD"), enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled"), modified: figure(Boolean(checkout.status), "git status --porcelain"), repository: figure(checkout.repository, "git remote get-url origin") }, validated: validatedFigures(idListing), upstream: {}, sourceDir: plugin.sourceDir, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: `git failed: ${error.message}`, error: error.message, aheadBy: null, matchedValidated: null })
+    }
+  }
+
+  rows.sort((a, b) => rowRank(a) - rowRank(b))
+  const needsAction = rows.some((row) => row.state === "ahead" || row.state === "diverged")
+  let updateRoute = null
+  let updateRouteError = null
+  if (needsAction) {
+    try {
+      updateRoute = await readers.route({ repoRoot: options.repoRoot })
+    } catch (error) {
+      updateRouteError = error?.message || String(error)
+    }
+  }
+  const drift = rows.filter((row) => row.state !== "validated")
+  return {
+    command: "audit",
+    catalog: {
+      source: live.source,
+      commit: figure(live.commit, live.source === "head" ? "marketplace default-branch HEAD" : "marketplace pin"),
+      readAt: figure(live.fetchedAt, live.source === "head" ? "liveRegistry fetchedAt" : "--offline or liveRegistry fallback"),
+      offline: options.offline === true,
+      reason: live.reason,
+    },
+    counts: {
+      installed: figure(installed.length, "omarchy plugin list --json length"),
+      selected: figure(selected.length, options.target ? "target selection" : "omarchy plugin list --json length"),
+      firstPartyExcluded: figure(firstPartyCount, "sourceType builtin or omarchy plugin list --json firstParty"),
+      audited: figure(rows.length, "audited row count"),
+      validated: figure(rows.length - drift.length, "rows whose state is validated"),
+      drift: figure(drift.length, "rows whose state is not validated"),
+    },
+    rows: options.drift ? drift : rows,
+    updateRoute,
+    updateRouteError,
+    ok: drift.length === 0,
+  }
+}

package/tools/audit/git.mjs

@@ -0,0 +1,63 @@
+// The local Git facts used by `omakit audit`. Every invocation is read-only,
+// has a fixed verb and argument shape, and is passed to Git without a shell.
+
+import { spawnSync } from "node:child_process"
+
+function runGit(sourceDir, args, env = process.env) {
+  const result = spawnSync("git", ["-C", sourceDir, ...args], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.status !== 0 || result.error) {
+    const detail = (result.stderr || result.error?.message || `git exited ${result.status}`).trim()
+    throw new Error(`${args.join(" ")}: ${detail}`)
+  }
+  return result.stdout.trim()
+}
+
+/** Read HEAD, tree state and origin from one checkout. */
+export function readCheckout(sourceDir, { env = process.env } = {}) {
+  return {
+    commit: runGit(sourceDir, ["rev-parse", "HEAD"], env).toLowerCase(),
+    status: runGit(sourceDir, ["status", "--porcelain"], env),
+    repository: runGit(sourceDir, ["remote", "get-url", "origin"], env),
+  }
+}
+
+/** A missing object is a local-history fact, not a failed ancestry check. */
+export function hasCommit(sourceDir, commit, { env = process.env } = {}) {
+  const result = spawnSync("git", ["-C", sourceDir, "cat-file", "-e", commit], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.error || result.status === null) throw new Error(result.error?.message || "git could not run")
+  return result.status === 0
+}
+
+export function isShallow(sourceDir, { env = process.env } = {}) {
+  const value = runGit(sourceDir, ["rev-parse", "--is-shallow-repository"], env)
+  if (!["true", "false"].includes(value)) throw new Error(`rev-parse --is-shallow-repository returned ${JSON.stringify(value)}`)
+  return value === "true"
+}
+
+/** Is a recorded commit an ancestor of the running checkout? */
+export function ancestorOf(sourceDir, commit, { env = process.env } = {}) {
+  const result = spawnSync("git", ["-C", sourceDir, "merge-base", "--is-ancestor", commit, "HEAD"], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.status === 0) return true
+  if (result.status === 1) return false
+  const detail = (result.stderr || result.error?.message || `git exited ${result.status}`).trim()
+  throw new Error(`merge-base --is-ancestor ${commit} HEAD: ${detail}`)
+}
+
+/** Count commits after one recorded ancestor. */
+export function commitsAfter(sourceDir, commit, { env = process.env } = {}) {
+  const value = runGit(sourceDir, ["rev-list", "--count", `${commit}..HEAD`], env)
+  if (!/^\d+$/.test(value)) throw new Error(`rev-list --count returned ${JSON.stringify(value)}`)
+  return Number(value)
+}

package/tools/audit/report.mjs

@@ -0,0 +1,56 @@
+import { action, AUDIT_VERDICTS, colourEnabled, field, GUTTER, mark, styler, verdict, wrap } from "../marketplace/style.mjs"
+
+const short = (value) => value ? String(value).slice(0, 8) : "unrecorded"
+const flagText = (flags) => flags.length ? `; ${flags.join(", ")}` : ""
+const markFor = (row) => {
+  if (row.flags.includes("modified")) return "advisory"
+  if (row.state === "validated") return "pass"
+  if (["ahead", "diverged", "unverified"].includes(row.state)) return "advisory"
+  if (row.state === "unlisted") return "info"
+  if (row.flags.includes("disabled")) return "info"
+  return "unknown"
+}
+
+function catalogText(catalog) {
+  if (catalog.source === "head") return `live HEAD ${short(catalog.commit.value)} at ${catalog.readAt?.value || "an unrecorded time"}`
+  return `pin ${short(catalog.commit.value)}${catalog.offline ? " (offline)" : ""}`
+}
+
+/** A terminal report made only from the shared style vocabulary. */
+export function renderAudit(document, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = []
+  out.push(...field("catalog", catalogText(document.catalog), c))
+  out.push(...field("installed", `${document.counts.installed.value}`, c))
+  out.push(...field("first-party", `${document.counts.firstPartyExcluded.value} left out`, c))
+  out.push(...field("audited", `${document.counts.audited.value}`, c))
+  out.push("")
+  for (const row of document.rows) {
+    const installed = row.installed?.commit?.value
+    const validated = row.matchedValidated?.commit?.value
+    const date = row.matchedValidated?.date?.value
+    const detail = ["validated", "ahead"].includes(row.state)
+      ? `${row.fact}${flagText(row.flags)}`
+      : `${row.state}: ${row.fact}${installed ? `; HEAD ${short(installed)}` : ""}${validated ? `; validated ${short(validated)}${date ? ` on ${date}` : ""}` : ""}${flagText(row.flags)}`
+    out.push(`${mark(markFor(row), c)}${c("name", row.id)}`)
+    out.push(...wrap(detail, { indent: GUTTER }, c))
+    if ((row.state === "ahead" || row.state === "diverged") && validated) {
+      out.push(...action(`git -C ${JSON.stringify(row.sourceDir)} checkout ${validated}`, c))
+    }
+    out.push("")
+  }
+  const total = document.counts.audited.value
+  const good = document.counts.validated.value
+  const drift = document.counts.drift.value
+  if (document.updateRoute) {
+    out.push(...action(`To validate a newer commit: ${document.updateRoute.url}`, c))
+    out.push(...wrap(`${document.updateRoute.name}; choose ${JSON.stringify(document.updateRoute.choice)}.`, { indent: GUTTER }, c))
+    out.push("")
+  }
+  if (document.updateRouteError) {
+    out.push(...wrap(`Verification route unavailable: ${document.updateRouteError}; run omakit pin.`, { indent: GUTTER }, c))
+    out.push("")
+  }
+  out.push(...verdict(document.ok ? "pass" : "fail", document.ok ? AUDIT_VERDICTS.validated : AUDIT_VERDICTS.drift, `${good} of ${total} run a commit the marketplace validated; ${drift} run one it never saw.`, c))
+  return out.join("\n")
+}

package/tools/marketplace/README.md

@@ -26,6 +26,7 @@ local commit through the transport seam the marketplace tests itself
 | `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
 | `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. Six states: `▁ ok`, `█ FAIL`, `▓ note`, `░ info`, `▒ ?` for a check that could not be made, and `▔ skip` for a check a flag said not to make, the floor's ink at the ceiling so it is never read as a pass. `docs/TUI.md` explains it. |
 | `report.mjs` | Text rendering of submit, watch, doctor and verify for the agent that runs this tool, and the person reading over its shoulder. |
+| `update-check.mjs` | A passive npm-release notice during normal terminal use, throttled to one check per day with a one-second network budget. Stores only installed/latest version metadata and time under XDG_STATE_HOME/omakit. Offline, JSON, pipes, help and CI skip it; DISABLE_UPDATE_NOTIFIER disables it. Version precedence and the registry GET are shared with doctor/upgrade. |
 | `path-hint.mjs` | Is `omakit` reachable as a bare command, and if not, the one line that makes it so for the install that is here: a symlink for a clone, the npm prefix's `bin` on PATH for a package, said for the shell in `$SHELL`. `setup` and `doctor` print it; nothing writes an rc file. |
 | `usage.mjs` | The help text, as data. |
 | `options.mjs` | Every option every command accepts, in one table, and the parser that reads a command line against it before anything runs; `tests/unit/options.test.mjs` holds the help signatures, and through them the completion scripts, to the table. |
@@ -99,3 +100,5 @@ online, the subject's default-branch HEAD and the marketplace's current
 registry, and `--offline` turns both off; `verify` needs no network at all
 beyond fetching a reviewer-mode subject, and `tests/parity/offline.mjs` proves
 it.
+
+`watch --list` discovers the signed-in account's open marketplace issues through `github.mjs`; `--user` bypasses the account lookup. `watch --all` runs the existing single-issue watch with four workers and shared repository HEAD promises, preserving each read failure. A bare terminal invocation uses `ask.mjs` to choose one or several issues. `report.mjs` composes the list and batch views; all options remain in `options.mjs` and `usage.mjs`, which also generate completion. The batch JSON retains complete single-issue reports; `current` compares commits and never substitutes for review or publication.

package/tools/marketplace/ask.mjs

@@ -17,6 +17,7 @@
 import { createInterface } from "node:readline"
 import { colourEnabled, STEP, action, styler, wrap } from "./style.mjs"
 import { resolveCategory, resolveTags } from "./form.mjs"
+import { watchIssueTitle } from "./watch.mjs"
 
 export class AskError extends Error {
   constructor(message) {
@@ -49,11 +50,13 @@ function reader(input) {
 }
 
 /** Ask one question until an answer resolves; `parse` returns { ok, value } or { ok: false, reason }. */
-async function question(lines, output, c, { name, heading, options, defaultIndexes, parse }) {
+async function question(lines, output, c, { name, heading, options, defaultIndexes, parse, wrapOptions = false, eofRemedy }) {
   const step = " ".repeat(STEP)
   output.write(`${wrap(heading, {}, c).join("\n")}\n`)
   for (const [index, option] of options.entries()) {
-    output.write(`${step}${c("typeable", String(index + 1).padStart(2))}  ${option}\n`)
+    output.write(wrapOptions
+      ? `${wrap(`${String(index + 1).padStart(2)} ${option}`, { indent: STEP }, c).join("\n")}\n`
+      : `${step}${c("typeable", String(index + 1).padStart(2))}  ${option}\n`)
   }
   const fallback = defaultIndexes.length ? defaultIndexes.map((index) => index + 1).join(",") : null
   const prompt = `${action(fallback ? `${name} [${fallback}]:` : `${name}:`, c, { indent: 0 })[0]} `
@@ -62,7 +65,7 @@ async function question(lines, output, c, { name, heading, options, defaultIndex
     const raw = await lines.next()
     if (raw === null) {
       output.write("\n")
-      throw new AskError(`stdin ended before the ${name} was answered; pass --${name} on the command line`)
+      throw new AskError(`stdin ended before the ${name} was answered; ${eofRemedy || `pass --${name} on the command line`}`)
     }
     const text = raw.trim() || (fallback ?? "")
     const parsed = parse(text)
@@ -138,3 +141,30 @@ export async function askChoices({ contract, defaults, missing, input = process.
   }
   return answers
 }
+
+/** Select one or several discovered issues; nothing is written or opened. */
+export async function askWatchIssues({ issues, input = process.stdin, output = process.stderr, colour = colourEnabled(output) }) {
+  const c = styler(colour)
+  const lines = reader(input)
+  try {
+    return await question(lines, output, c, {
+      name: "issues",
+      heading: "Choose list numbers, comma-separated; all checks every issue, q cancels.",
+      options: issues.map((issue) => `#${issue.number} ${watchIssueTitle(issue.title)}`),
+      defaultIndexes: [],
+      wrapOptions: true,
+      eofRemedy: "pass an issue URL, --all or --list on the command line",
+      parse: (text) => {
+        if (text.toLowerCase() === "q") return { ok: true, value: [] }
+        if (text.toLowerCase() === "all") return { ok: true, value: issues }
+        const indexes = text.split(",").map((value) => value.trim())
+        if (indexes.some((value) => !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > issues.length)) {
+          return { ok: false, reason: `Answer with list numbers from 1 to ${issues.length}, all, or q.` }
+        }
+        return { ok: true, value: [...new Set(indexes.map(Number))].map((index) => issues[index - 1]) }
+      },
+    })
+  } finally {
+    lines.close()
+  }
+}

package/tools/marketplace/cli.mjs

@@ -21,24 +21,27 @@ import { ensurePin, MARKETPLACE_PIN, requirePin } from "./pin.mjs"
 import { marketplaceBaselineSection } from "./verify.mjs"
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
 import { submitPreflight } from "./submit.mjs"
-import { askChoices } from "./ask.mjs"
-import { validationWatch } from "./watch.mjs"
-import { renderSubmit, renderWatch, renderDoctor, renderVerify } from "./report.mjs"
+import { askChoices, askWatchIssues } from "./ask.mjs"
+import { validationWatch, discoverWatchIssues, validationWatchAll } from "./watch.mjs"
+import { renderSubmit, renderWatch, renderWatchList, renderWatchAll, renderDoctor, renderVerify } from "./report.mjs"
 import { consequence } from "./preflight.mjs"
 import { doctor } from "./doctor.mjs"
 import { completionStep, setup } from "./setup.mjs"
 import { staleCompletionNotice } from "./completion-check.mjs"
 import { ACCEPTED, acceptedWords, checkArgs } from "./options.mjs"
 import { upgrade } from "./upgrade.mjs"
+import { updateCheckEnabled, updateNotice } from "./update-check.mjs"
 import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
-import { action, colourEnabled, GUTTER, labelled, mark, styler, verdict, wrap } from "./style.mjs"
+import { action, AUDIT_VERDICTS, colourEnabled, GUTTER, labelled, mark, styler, verdict, wrap } from "./style.mjs"
 import { omakitCacheDir, withHomeAbbreviated } from "./paths.mjs"
 import { DEFAULTS as WEIGH_DEFAULTS, measureWeigh, planWeigh } from "../weigh/audit.mjs"
 import { confirmationQuestion, renderList, renderWeigh, renderPlan } from "../weigh/report.mjs"
 import { listWeighings } from "../weigh/list.mjs"
 import { askYes } from "../weigh/confirm.mjs"
+import { auditInstalled } from "../audit/audit.mjs"
+import { renderAudit } from "../audit/report.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -60,6 +63,7 @@ const REMEDY = Object.freeze({
   "github-unavailable": "Wait for GitHub, then run it again. `gh auth login` raises the rate limit if that is what ran out.",
   "not-found": "Check the issue URL: it has to be an existing issue on the marketplace repository.",
   "head-unreadable": "Check that the plugin repository is public and its URL is right.",
+  "login-required": "gh auth login",
   "not-confirmed": "Run it again and answer y, or pass --yes when the person whose shell it is has agreed.",
   "interrupted": "shell.json was restored; run it again when the desktop is yours to restart.",
 })
@@ -178,18 +182,41 @@ async function cmdSubmit(args) {
 
 async function cmdWatch(args) {
   const issueUrl = positionals(args)[0]
-  if (!issueUrl) fail("usage", "watch needs an issue: `omakit watch <issue-url>`", 2)
+  const all = args.includes("--all")
+  const list = args.includes("--list")
+  const user = option(args, "--user")
+  const interactive = !args.includes("--json") && !option(args, "--out") && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)
+  if ((all && list) || (issueUrl && (all || list || user !== undefined))) {
+    fail("usage", "Use an issue URL, --all, or --list; --user belongs to account-wide discovery.", 2)
+  }
+  if (!issueUrl && !all && !list && !interactive) {
+    fail("usage", "watch needs an issue or a mode: `omakit watch <issue-url>`, `omakit watch --all`, or `omakit watch --list`. A terminal can pick issues with `omakit watch`.", 2)
+  }
   const spinner = spinnerFor(args)
   let result
   try {
-    result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
+    if (issueUrl) {
+      result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
+    } else {
+      const discovery = await discoverWatchIssues({ user, onPhase: spinner.phase })
+      if (list) {
+        result = discovery
+      } else {
+        if (!all && discovery.issues.length) {
+          spinner.done()
+          discovery.issues = await askWatchIssues({ issues: discovery.issues })
+        }
+        result = await validationWatchAll({ repoRoot: ROOT, discovery, onPhase: spinner.phase })
+      }
+    }
   } catch (error) {
     spinner.done()
     failFrom(error)
   }
   spinner.done()
-  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderWatch(result))
-  process.exit(result.verdict.state === "unknown" ? 2 : 0)
+  const render = result.mode === "list" ? renderWatchList : result.mode === "all" ? renderWatchAll : renderWatch
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : render(result))
+  process.exit(result.verdict?.state === "unknown" || result.summary?.unknown > 0 ? 2 : 0)
 }
 
 async function cmdFrontDoor() {
@@ -293,6 +320,40 @@ async function cmdParity(args) {
   process.exit(ok ? 0 : 1)
 }
 
+function notAudited(message, remedy = null, exit = 1) {
+  const c = styler(colourEnabled(process.stderr))
+  const lines = verdict("fail", AUDIT_VERDICTS.unavailable, message, c)
+  if (remedy) lines.push(...action(remedy, c, { indent: 0 }))
+  process.stderr.write(`${lines.join("\n")}\n`)
+  process.exit(exit)
+}
+
+async function cmdAudit(args) {
+  const parsed = checkArgs(args, ACCEPTED.audit)
+  if (parsed.offending !== null) notAudited(`${parsed.reason}. Accepted: ${acceptedWords("audit")}.`, "omakit audit [<plugin-id-or-dir>] [--drift] [--json] [--out FILE] [--offline]", 2)
+  let document
+  try {
+    document = await auditInstalled({
+      repoRoot: ROOT,
+      target: parsed.positionals[0],
+      drift: parsed.options.has("--drift"),
+      offline: parsed.options.has("--offline"),
+    })
+  } catch (error) {
+    if (error?.code && typeof error.code === "string") notAudited(`${error.message}.`, error.remedy || REMEDY[error.code])
+    throw error
+  }
+  const json = `${JSON.stringify(document, null, 2)}\n`
+  const out = parsed.options.get("--out")
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true })
+    writeFileSync(resolve(out), json)
+  }
+  if (parsed.options.has("--json")) process.stdout.write(json)
+  else process.stdout.write(`${renderAudit(document)}\n`)
+  process.exit(document.ok ? 0 : 1)
+}
+
 /**
  * Every way `weigh` stops without weighing, in one register: the closing
  * word a report would have ended with, negated, then the sentence naming
@@ -424,6 +485,11 @@ const [command, ...rest] = process.argv.slice(2)
 // completion script names another omakit, so `omakit we<TAB>` may not know
 // `weigh`. One stat and one short read; never under a pipe, whose stderr
 // stays empty on success, and never for setup, which is the fix.
+if (updateCheckEnabled({ command, args: rest, stdinTTY: process.stdin.isTTY, stdoutTTY: process.stdout.isTTY, stderrTTY: process.stderr.isTTY })) {
+  const notice = await updateNotice({ repoRoot: ROOT, version: VERSION })
+  if (notice) process.stderr.write(`${wrap(notice, {}, styler(colourEnabled(process.stderr))).join("\n")}\n`)
+}
+
 if (command !== "setup" && process.stderr.isTTY) {
   const notice = staleCompletionNotice({ version: VERSION })
   if (notice) process.stderr.write(`${styler(colourEnabled(process.stderr))("label", notice)}\n`)
@@ -458,6 +524,8 @@ if (command === "setup") {
   await cmdVerify(rest)
 } else if (command === "parity") {
   await cmdParity(rest)
+} else if (command === "audit") {
+  await cmdAudit(rest)
 } else if (command === "weigh") {
   await cmdWeigh(rest)
 } else if (command === "help" || command === "--help" || command === "-h" || command === undefined) {

package/tools/marketplace/completion.mjs

@@ -47,7 +47,8 @@ export function subcommandsOf(commands = COMMANDS) {
 }
 
 /**
- * The plugin ids a TAB offers for `omakit weigh <TAB>`: what the running
+ * The plugin ids a TAB offers for `omakit weigh <TAB>` and `omakit audit <TAB>`:
+ * what the running
  * shell reports through `omarchy-shell shell listPlugins`, filtered with
  * `jq` at TAB time, enabled ids first and whole bars left out, since a bar
  * cannot be weighed. No node process behind the TAB: a shell that does not

package/tools/marketplace/doctor.mjs

@@ -42,7 +42,7 @@ import { join } from "node:path"
 import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
 import { LIVE_PATHS } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
-import { NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
+import { compareVersions, NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
 import { completionStatus } from "./completion-check.mjs"
 
@@ -205,11 +205,17 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     phase("asking the npm registry for the newest published version")
     const published = await latestVersion(self.name)
     if (published.version) {
-      const current = published.version === self.version
-      versionCheck(current ? "ok" : "advice",
-        current ? `${self.version}, the newest published version` : `${self.version}; ${published.version} is published`,
-        current ? null : `run \`${upgradeCommand(repoRoot, self.name)}\``,
-        published.version, NPM_REGISTRY)
+      const comparison = compareVersions(published.version, self.version)
+      if (comparison === null) {
+        versionCheck("unknown", `${self.version}; the installed or published version is invalid`)
+      } else {
+        versionCheck(comparison > 0 ? "advice" : "ok",
+          comparison === 0 ? `${self.version}, the newest published version`
+            : comparison < 0 ? `${self.version}; ahead of the newest published version ${published.version}`
+              : `${self.version}; ${published.version} is published`,
+          comparison > 0 ? `run \`${upgradeCommand(repoRoot, self.name)}\`` : null,
+          published.version, NPM_REGISTRY)
+      }
     } else {
       versionCheck("unknown", `${self.version}; could not read the npm registry (${published.error?.code || "error"})`)
     }

package/tools/marketplace/form.mjs

@@ -23,7 +23,7 @@ import { readFileSync } from "node:fs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { parseYaml } from "./yaml.mjs"
-import { requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
 
 export const SUBMIT_FORM_PATH = ".github/ISSUE_TEMPLATE/submit-plugin.yml"
 export const OFFICIAL_SUBMISSION_MODULE = "scripts/submission.mjs"
@@ -147,7 +147,7 @@ export async function submissionContract(options = {}) {
  * pick something the form no longer offers.
  *
  * @param {{ repoRoot?: string, pinDir?: string }} [options]
- * @returns {Promise<{ formPath: string, name: string, choice: string }>}
+ * @returns {Promise<{ formPath: string, name: string, choice: string, url: string }>}
  */
 export async function newerCommitChoice(options = {}) {
   const pinDir = options.pinDir || requirePin(options.repoRoot).dir
@@ -164,7 +164,9 @@ export async function newerCommitChoice(options = {}) {
   }
   const name = typeof form.name === "string" ? form.name.trim() : ""
   if (!name) throw new ContractError("form-shape-changed", `${VERIFY_FORM_PATH} has no name`)
-  return { formPath: VERIFY_FORM_PATH, name, choice }
+  const url = new URL(`${MARKETPLACE_PIN.repository.replace(/\/$/, "")}/issues/new`)
+  url.searchParams.set("template", VERIFY_FORM_PATH.split("/").at(-1))
+  return { formPath: VERIFY_FORM_PATH, name, choice, url: url.href }
 }
 
 /**

package/tools/marketplace/github.mjs

@@ -109,7 +109,7 @@ 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 } = {}) {
+async function get(url, { accept, signal } = {}) {
   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
@@ -125,7 +125,7 @@ async function get(url, { accept } = {}) {
   if (auth) headers.authorization = `Bearer ${auth}`
   let response
   try {
-    response = await fetch(url, { method: "GET", headers, redirect: "follow" })
+    response = await fetch(url, { method: "GET", headers, redirect: "follow", ...(signal ? { signal } : {}) })
   } 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
@@ -150,8 +150,8 @@ async function get(url, { accept } = {}) {
   return response
 }
 
-export async function getJson(url) {
-  return (await get(url)).json()
+export async function getJson(url, options) {
+  return (await get(url, options)).json()
 }
 
 export async function getText(url, accept) {
@@ -171,17 +171,38 @@ export async function issue(owner, repository, number) {
   return getJson(`https://api.github.com/repos/${owner}/${repository}/issues/${number}`)
 }
 
-export async function issueComments(owner, repository, number, maxPages = 10) {
+/** 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.")
+  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
+}
+
+/** Repository issues by their creator. PRs are excluded; pagination never silently truncates. */
+export async function repositoryIssues(owner, repository, creator, { readJson = getJson, maxPages = 100 } = {}) {
+  const all = []
+  for (let page = 1; page <= maxPages; page += 1) {
+    const query = new URLSearchParams({ creator, state: "open", sort: "updated", direction: "desc", per_page: "100", page: String(page) })
+    const batch = await readJson(`https://api.github.com/repos/${owner}/${repository}/issues?${query}`)
+    if (!Array.isArray(batch)) throw new GitHubError("github-unavailable", "GitHub did not return an issue list")
+    all.push(...batch.filter((item) => !item.pull_request))
+    if (batch.length < 100) return all
+  }
+  throw new GitHubError("issue-list-incomplete", `The issue list exceeded ${maxPages} pages; no complete account-wide result is available`)
+}
+
+export async function issueComments(owner, repository, number, maxPages = 10, readJson = getJson) {
   const all = []
   for (let page = 1; page <= maxPages; page += 1) {
-    const batch = await getJson(
+    const batch = await readJson(
       `https://api.github.com/repos/${owner}/${repository}/issues/${number}/comments?per_page=100&page=${page}`,
     )
-    if (!Array.isArray(batch) || !batch.length) break
+    if (!Array.isArray(batch)) throw new GitHubError("github-unavailable", "GitHub did not return issue comments")
     all.push(...batch)
-    if (batch.length < 100) break
+    if (batch.length < 100) return all
   }
-  return all
+  throw new GitHubError("comments-incomplete", `Issue #${number} exceeded ${maxPages} comment pages; its latest baseline cannot be determined`)
 }
 
 /**

package/tools/marketplace/options.mjs

@@ -21,12 +21,13 @@ export const ACCEPTED = Object.freeze({
   setup: Object.freeze({ valued: [], flags: ["--yes", "--completion"], positionals: 0 }),
   pin: Object.freeze({ valued: [], flags: [], positionals: 0 }),
   submit: Object.freeze({ valued: ["--category", "--tags", "--notes", "--suggest-tag", "--name", "--out"], flags: ["--offline", "--allow-dirty", "--json"], positionals: 1 }),
-  watch: Object.freeze({ valued: ["--out"], flags: ["--json"], positionals: 1 }),
+  watch: Object.freeze({ valued: ["--out", "--user"], flags: ["--json", "--all", "--list"], positionals: 1 }),
   verify: Object.freeze({ valued: ["--out"], flags: ["--allow-dirty", "--json"], positionals: 1 }),
   help: Object.freeze({ valued: [], flags: ["--agent"], positionals: 0 }),
   upgrade: Object.freeze({ valued: [], flags: ["--dry-run"], positionals: 0 }),
   doctor: Object.freeze({ valued: ["--out"], flags: ["--offline", "--json"], positionals: 0 }),
   parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
+  audit: Object.freeze({ valued: ["--out"], flags: ["--drift", "--json", "--offline"], positionals: 1 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
 })
 

package/tools/marketplace/report.mjs

@@ -21,6 +21,7 @@ import {
   action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
 } from "./style.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
+import { watchIssueTitle } from "./watch.mjs"
 
 const body = " ".repeat(GUTTER)
 
@@ -244,6 +245,50 @@ export function renderWatch(result, { colour = colourEnabled() } = {}) {
   return out.join("\n")
 }
 
+/** Discovery is cheap: issue metadata and repeatable commands, no plugin HEAD reads. */
+export function renderWatchList(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = [...field("account", result.account, c), ...field("issues", `${result.issues.length} open marketplace issue(s)`, c), ""]
+  for (const issue of result.issues) {
+    out.push(...wrap(`#${issue.number} ${watchIssueTitle(issue.title)}`, {}, c))
+    out.push(...field("state", `${issue.state}${issue.labels.length ? `; labels ${issue.labels.map(watchIssueTitle).join(", ")}` : ""}`, c))
+    out.push(...action(`omakit watch ${issue.url}`, c, { indent: 0 }), "")
+  }
+  if (!result.issues.length) out.push(...wrap("No open marketplace issues found for this account.", {}, c))
+  else out.push(...action(`omakit watch --all --user ${result.account}`, c, { indent: 0 }))
+  return out.join("\n")
+}
+
+/** 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), ""]
+  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.error) {
+      out.push(...field("read error", watchIssueTitle(`${row.error.code}: ${row.error.message}`), c))
+    } else {
+      const report = row.report
+      out.push(...field("baseline", report.validated ? `${report.validated.outcome}; ${report.validated.findings.length} finding(s); capabilities ${report.validated.capabilities.join(", ") || "none"}` : "no complete baseline", c))
+      out.push(...field("state", `${report.read.state}; labels ${report.read.labels.map(watchIssueTitle).join(", ") || "none"}`, c))
+      if (state !== "current") out.push(...field("comparison", report.verdict.summary, c))
+      if (report.discussion) {
+        const text = watchIssueTitle(report.discussion.body).replace(/\s+/g, " ").trim()
+        out.push(...field("discussion", text.length > 240 ? `${text.slice(0, 240)}…` : text, c))
+        if (report.discussion.url) out.push(...field("source", report.discussion.url, c, { wrapValue: false }))
+      }
+      if (report.verdict.action) out.push(...action(report.verdict.action, c, { indent: 0 }))
+    }
+    out.push("")
+  }
+  if (!result.issues.length) out.push(...wrap("No issues selected for checking.", {}, c))
+  out.push(...wrap("Current means the validated commit matches HEAD. It does not mean review, approval or publication is complete. Read-only; this run posts nothing.", {}, c))
+  return out.join("\n")
+}
+
 /** A list of paths at fault, the way a failing check prints them: a tinted dash, the path in the placeholder tint. */
 function pathLines(paths, c, dash = "fail") {
   return paths.flatMap((path) => wrap(`- ${path}`, { indent: GUTTER + STEP, first: GUTTER })

package/tools/marketplace/style.mjs

@@ -198,6 +198,12 @@ export const STATUS = Object.freeze({
   skipped: Object.freeze({ glyph: DENSITY.ceiling, word: "skip", tint: "unknown" }),
 })
 
+export const AUDIT_VERDICTS = Object.freeze({
+  validated: "AUDITED",
+  drift: "DRIFT",
+  unavailable: "NOT AUDITED",
+})
+
 /** The width of the widest mark, "█ FAIL"; every mark is padded to it so the names beside them align. */
 export const MARK_WIDTH = Math.max(...Object.values(STATUS).map((s) => `${s.glyph} ${s.word}`.length))
 

package/tools/marketplace/update-check.mjs

@@ -0,0 +1,48 @@
+// A passive npm-version notice. Only metadata and a throttle stamp are stored;
+// nothing is installed or executed. Explicit doctor checks bypass this throttle.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import { compareVersions, registryLatest, upgradeCommand } from "./upgrade.mjs"
+
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+export const UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
+export const UPDATE_CHECK_TIMEOUT_MS = 1000
+
+export function updateCheckEnabled({ command, args = [], stdinTTY, stdoutTTY, stderrTTY, env = process.env }) {
+  return Boolean(stdinTTY && stdoutTTY && stderrTTY)
+    && !env.DISABLE_UPDATE_NOTIFIER && !env.CI
+    && !args.some((arg) => arg === "--offline" || arg === "--json" || arg === "--agent" || arg === "--out" || arg.startsWith("--out="))
+    && (command === undefined || ["watch", "submit", "verify", "audit", "weigh"].includes(command))
+    && !args.includes("--help") && !args.includes("-h")
+}
+
+/** At most one registry read and one notice per successful day (failure retries after an hour). */
+export async function updateNotice({ repoRoot, version, name = "omakit", env = process.env, now = Date.now(), latest = registryLatest, timeoutMs = UPDATE_CHECK_TIMEOUT_MS }) {
+  if (compareVersions(version, version) === null) return null
+  const updateFile = join(env.XDG_STATE_HOME || join(homedir(), ".local/state"), "omakit", "update-check.json")
+  try {
+    const cached = JSON.parse(readFileSync(updateFile, "utf8"))
+    const age = now - cached.checkedAt
+    const validMetadata = cached.latest === null || compareVersions(cached.latest, cached.latest) !== null
+    if (cached.installed === version && cached.name === name && validMetadata && Number.isFinite(age) && age >= 0
+      && age < (cached.latest ? UPDATE_CHECK_INTERVAL_MS : UPDATE_RETRY_INTERVAL_MS)) return null
+  } catch { /* Missing or malformed state triggers a fresh bounded read. */ }
+  const controller = new AbortController()
+  let timer
+  let published
+  try {
+    published = await Promise.race([
+      Promise.resolve().then(() => latest(name, { signal: controller.signal })).catch(() => ({ version: null })),
+      new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve({ version: null }) }, timeoutMs) }),
+    ])
+  } finally { clearTimeout(timer) }
+  const newest = compareVersions(published?.version, published?.version) === null ? null : published.version
+  try {
+    mkdirSync(dirname(updateFile), { recursive: true })
+    writeFileSync(updateFile, `${JSON.stringify({ name, installed: version, latest: newest, checkedAt: now })}\n`, { mode: 0o600 })
+  } catch { /* An unwritable state directory must not break the user's command. */ }
+  return newest && compareVersions(newest, version) > 0
+    ? `Omakit ${newest} is available (installed ${version}). Run \`${upgradeCommand(repoRoot, name)}\`.`
+    : null
+}

package/tools/marketplace/upgrade.mjs

@@ -74,9 +74,12 @@ export const NPM_REGISTRY = "https://registry.npmjs.org"
  *
  * @returns {Promise<{ version: string|null, error: { code: string, message: string }|null }>}
  */
-export async function registryLatest(name) {
+export async function registryLatest(name, { signal } = {}) {
   try {
-    const meta = await getJson(`${NPM_REGISTRY}/${encodeURIComponent(name)}/latest`)
+    const meta = await getJson(`${NPM_REGISTRY}/${encodeURIComponent(name)}/latest`, { signal })
+    if (meta?.version && compareVersions(meta.version, meta.version) === null) {
+      return { version: null, error: { code: "invalid-version", message: "the registry did not return a valid semantic version" } }
+    }
     return meta?.version
       ? { version: meta.version, error: null }
       : { version: null, error: { code: "unpublished", message: "the registry answered without a version" } }
@@ -85,6 +88,33 @@ export async function registryLatest(name) {
   }
 }
 
+/** Semantic precedence, including prereleases; invalid versions are never update targets. */
+export function compareVersions(left, right) {
+  const parse = (value) => {
+    const match = String(value || "").match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/)
+    if (!match) return null
+    const pre = match[4]?.split(".") || []
+    if (pre.some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith("0"))) return null
+    return { core: match.slice(1, 4).map(BigInt), pre }
+  }
+  const a = parse(left), b = parse(right)
+  if (!a || !b) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1
+  }
+  if (!a.pre.length || !b.pre.length) return a.pre.length === b.pre.length ? 0 : a.pre.length ? -1 : 1
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    const x = a.pre[index], y = b.pre[index]
+    if (x === undefined || y === undefined) return x === y ? 0 : x === undefined ? -1 : 1
+    if (x === y) continue
+    const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y)
+    if (xn && yn) return BigInt(x) > BigInt(y) ? 1 : -1
+    if (xn !== yn) return xn ? -1 : 1
+    return x > y ? 1 : -1
+  }
+  return 0
+}
+
 function installedVersion(repoRoot) {
   try {
     return JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version || null
@@ -300,8 +330,10 @@ async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, ref
   if (!newest) {
     return refuse("the npm registry did not answer, so there is nothing to compare against.", "Connect to the network, then run `omakit upgrade` again.")
   }
-  if (newest === current) {
-    ok(`already current at ${current}, the newest published version`)
+  const compared = compareVersions(newest, current)
+  if (compared === null) return refuse("the installed or published version is invalid, so an exact newer release cannot be selected.")
+  if (compared <= 0) {
+    ok(compared === 0 ? `already current at ${current}, the newest published version` : `${current} is ahead of the newest published version ${newest}; no downgrade applied`)
     out()
     lines(wrap("The marketplace pin is a separate thing and is never touched here. `omakit doctor` says whether it is behind.", {}, c))
     return { ok: true, changed: false, version: current }

package/tools/marketplace/usage.mjs

@@ -39,6 +39,17 @@ export const COMMANDS = Object.freeze([
       `Read-only, exact commit ${MARKETPLACE_PIN.commit}.`,
     ],
   },
+  {
+    signature: [
+      "omakit audit <plugin-id-or-dir> [--drift] [--json] [--out <file>] [--offline]",
+      "omakit audit [--drift] [--json] [--out <file>] [--offline]",
+    ],
+    lines: [
+      "Compare every installed third-party plugin's running commit with the",
+      "exact commits the marketplace records as validated. Read-only. --drift",
+      "shows only rows that are not validated; --offline reads the pin.",
+    ],
+  },
   {
     signature: [
       "omakit submit <target> --category <c> --tags <a,b> [--notes <text>]",
@@ -58,11 +69,18 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: "omakit watch <issue-url> [--json] [--out <file>]",
+    signature: [
+      "omakit watch <issue-url> [--json] [--out <file>]",
+      "omakit watch [--all | --list] [--user <login>] [--json] [--out <file>]",
+    ],
     lines: [
       "Compare the commit the marketplace validated on a submission issue with",
       "the plugin repository's current default-branch HEAD, and say what makes",
       "it validate a newer one. Read-only.",
+      "--all checks your open marketplace issues; --list lists them first.",
+      "Without a URL or either flag, a terminal asks which issues to check.",
+      "Uses your gh account, or --user to read another public account. JSON",
+      "and pipes never prompt: use --all or --list. Each run is one snapshot.",
     ],
   },
   {
@@ -93,6 +111,8 @@ export const COMMANDS = Object.freeze([
     lines: [
       "What is installed, what is pinned, and what has moved since. Reads and",
       "prints; it installs nothing and never moves the pin.",
+      "Checks the newest npm release explicitly. Normal terminal use also",
+      "checks at most once daily; DISABLE_UPDATE_NOTIFIER=1 disables notices.",
     ],
   },
   {

package/tools/marketplace/watch.mjs

@@ -29,7 +29,7 @@
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
-import { defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
+import { authenticatedUser, repositoryIssues, defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
 
 export class WatchError extends Error {
   constructor(code, message) {
@@ -41,6 +41,70 @@ export class WatchError extends Error {
 
 const MARKETPLACE_SLUG = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "").toLowerCase()
 
+/** Text from an issue remains data, including at a terminal. JSON retains the original title. */
+export function watchIssueTitle(value) {
+  return String(value || "").replace(/[\p{Cc}\p{Cf}]/gu, " ")
+}
+
+/** Discover the account's open marketplace issues, without reading every plugin. */
+export async function discoverWatchIssues({ user, github = {}, onPhase = () => {} } = {}) {
+  const read = { authenticatedUser, repositoryIssues, ...github }
+  if (user !== undefined && !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(user)) {
+    throw new WatchError("usage", "--user needs a GitHub login, not a URL or search query")
+  }
+  onPhase("reading the GitHub account")
+  const account = user || await read.authenticatedUser()
+  const [owner, repository] = MARKETPLACE_SLUG.split("/")
+  onPhase(`reading open marketplace issues for ${account}`)
+  const subjects = await read.repositoryIssues(owner, repository, account)
+  // Check the response as well as the server-side creator filter. Never turn
+  // another author's issue, or a PR, into an account-wide watch target.
+  const seen = new Set()
+  const issues = subjects.filter((subject) => {
+    if (subject.pull_request || subject.state !== "open" || subject.user?.login?.toLowerCase() !== account.toLowerCase()) return false
+    if (!Number.isSafeInteger(subject.number) || subject.number < 1 || seen.has(subject.number)) return false
+    seen.add(subject.number)
+    return true
+  }).map((subject) => ({
+    number: subject.number,
+    url: `${MARKETPLACE_PIN.repository}/issues/${subject.number}`,
+    title: subject.title,
+    state: subject.state,
+    labels: (subject.labels || []).map((label) => typeof label === "string" ? label : label?.name).filter(Boolean),
+    updatedAt: subject.updated_at || null,
+  }))
+  return { mode: "list", account, marketplace: MARKETPLACE_PIN.repository, issues }
+}
+
+/** A batch keeps independent read failures visible and shares repository HEAD reads. */
+export async function validationWatchAll({ repoRoot, discovery, github = {}, onPhase = () => {} }) {
+  if (discovery.issues.length) requirePin(repoRoot)
+  const heads = new Map()
+  const readHead = github.defaultBranchHead || defaultBranchHead
+  const shared = { ...github, defaultBranchHead: (url) => {
+    if (!heads.has(url)) heads.set(url, Promise.resolve().then(() => readHead(url)))
+    return heads.get(url)
+  } }
+  const results = new Array(discovery.issues.length)
+  let next = 0
+  async function worker() {
+    while (next < discovery.issues.length) {
+      const index = next++
+      const target = discovery.issues[index]
+      onPhase(`checking issue #${target.number} (${index + 1}/${discovery.issues.length})`)
+      try {
+        results[index] = { issue: target, report: await validationWatch({ repoRoot, issueUrl: target.url, github: shared }), error: null }
+      } catch (error) {
+        results[index] = { issue: target, report: null, error: { code: error.code || "watch-unavailable", message: error.message } }
+      }
+    }
+  }
+  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 }
+}
+
 // The one action that re-runs validation, in the register the marketplace itself
 // uses in its own failure feedback.
 export const REFRESH_ACTION =
@@ -207,6 +271,12 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase, github = {}
     baselineError,
     head,
     headError,
+    discussion: maintainerComments.length ? {
+      body: maintainerComments.at(-1).body || "",
+      url: maintainerComments.at(-1).html_url || null,
+      createdAt: maintainerComments.at(-1).created_at || null,
+      authorAssociation: maintainerComments.at(-1).author_association || null,
+    } : null,
     verdict: validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl }),
   }
 }

package/tools/weigh/list.mjs

@@ -43,12 +43,13 @@ export function lastWeighings(stateDir) {
 }
 
 /**
- * One row per installed plugin, sorted: enabled and not weighed first (by
- * id), then enabled and weighed, oldest weighing first, then disabled.
+ * The installed-plugin list joined to the manifest catalog by id. This is the
+ * one join used by both `weigh --list` and `audit`, so a source directory has
+ * one authority throughout the tool.
  *
  * @param {{ env?: NodeJS.ProcessEnv }} [options]
  */
-export function listWeighings({ env = process.env } = {}) {
+export function installedPlugins({ env = process.env } = {}) {
   const listed = run("listPlugins", { env })
   if (!listed.ok) throw new WeighError("shell-not-running", "omarchy plugin list did not answer, and the list is what the shell has installed", "omarchy-restart-shell")
   let installed
@@ -57,6 +58,7 @@ export function listWeighings({ env = process.env } = {}) {
   } catch {
     throw new WeighError("shell-unreadable", "omarchy plugin list did not answer with JSON", "omarchy-restart-shell, then run it again.")
   }
+  if (!Array.isArray(installed)) throw new WeighError("shell-unreadable", "omarchy plugin list did not answer with a JSON array", "omarchy-restart-shell, then run it again.")
   const catalogRun = run("catalog", { env })
   let catalog = []
   try {
@@ -65,6 +67,17 @@ export function listWeighings({ env = process.env } = {}) {
     catalog = []
   }
   const sourceDirOf = (id) => catalog.find((entry) => entry.id === id)?.sourceDir || null
+  return installed.map((plugin) => ({ ...plugin, sourceDir: sourceDirOf(plugin.id) }))
+}
+
+/**
+ * One row per installed plugin, sorted: enabled and not weighed first (by
+ * id), then enabled and weighed, oldest weighing first, then disabled.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ */
+export function listWeighings({ env = process.env } = {}) {
+  const installed = installedPlugins({ env })
   const stateDir = omakitStateDir("weigh", env)
   const latest = lastWeighings(stateDir)
   const rows = installed.map((plugin) => {
@@ -76,7 +89,7 @@ export function listWeighings({ env = process.env } = {}) {
       kinds,
       enabled: plugin.enabled === true,
       firstParty: plugin.firstParty === true,
-      sourceDir: sourceDirOf(plugin.id),
+      sourceDir: plugin.sourceDir,
       weighable: !kinds.includes("bar"),
       lastWeighed: last ? { date: last.date, readme: last.readme, summary: last.summary, document: last.document } : null,
       enable: plugin.enabled === true ? null : `omarchy plugin enable ${plugin.id}`,