clearotron 0.3.2-beta.10 → 0.3.2-beta.11

package/scripts/generated-files-are-current.mjs

@@ -60,6 +60,19 @@ export function treeState(root = ROOT) {
  * a path whose STATE changed — staged to modified, say — is reported as having moved, and the paths are
  * returned rather than a count, because two numbers agreeing is not the same as two sets agreeing.
  */
+/**
+ * The `git status --porcelain` LINES that differ between two readings, status included. `movedPaths`
+ * names what moved; this keeps the two-character state, which is what says whether a path is tracked.
+ */
+export function movedLines(before, after) {
+  const bag = (s) => { const m = new Map(); for (const l of String(s).split("\n")) if (l.trim()) m.set(l, (m.get(l) ?? 0) + 1); return m; };
+  const [b, a] = [bag(before), bag(after)];
+  const out = new Set();
+  for (const [l, n] of a) if ((b.get(l) ?? 0) !== n) out.add(l);
+  for (const [l, n] of b) if ((a.get(l) ?? 0) !== n) out.add(l);
+  return [...out];
+}
+
 export function movedPaths(before, after) {
   const bag = (s) => {
     const m = new Map();
@@ -84,6 +97,7 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
   const unreadable = [];
   const wrote = [];
   const unattributable = [];
+  const neighbours = [];
   for (const m of found) {
     // ── `--check` IS A CONTRACT, AND NOTHING WAS VERIFYING IT ──────────────────────────────────────
     //
@@ -125,14 +139,25 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
     const out = ((r.stdout || "") + (r.stderr || "")).trim();
     if (before !== null && after !== null && before !== after) {
       const moved = movedPaths(before, after);
-      if (before.trim() === "") {
+      // AN UNTRACKED PATH IS NOT A MINTER'S TO WRITE. A minter that ignores `--check` re-mints its own
+      // generated file, which is tracked, so its write reads as a MODIFIED path. A path that appears or
+      // goes as untracked (`??`) was written by something else — in the suite, the neighbour test running
+      // beside this one — and it touched nothing a minter reads. So it is named, with who it was not, and
+      // this minter's answer is read as it came back. Measured on a suite run: `mint-public-residue`
+      // printed "the backlog is current" and was named as having changed the tree, because a neighbour
+      // had just made a directory inside the checkout.
+      if (movedLines(before, after).every((l) => l.startsWith("?? "))) {
+        neighbours.push({ m, moved });
+        log(`  (another process wrote ${moved.join(", ")} while ${m} ran — untracked, so not this minter's output)`);
+      } else if (before.trim() === "") {
         wrote.push({ m, out, moved });
         log(`  WROTE    ${m} (during --check): ${moved.join(", ") || "the tree moved"}`);
+        continue;
       } else {
         unattributable.push({ m, moved });
         log(`  ?        ${m} — the tree moved and this probe cannot say who moved it: ${moved.join(", ") || "paths unknown"}`);
+        continue;
       }
-      continue;
     }
     // 0 is current, 1 is stale, anything else is a minter that could not look — reported separately,
     // because "I could not read the tree" and "the file is out of date" need different things done.
@@ -141,11 +166,11 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
     unreadable.push({ m, out, code: r.status });
     log(`  ?        ${m} (exit ${r.status})`);
   }
-  return { found, stale, unreadable, wrote, unattributable, empty: false, contractChecked: readTree() !== null };
+  return { found, stale, unreadable, wrote, unattributable, neighbours, empty: false, contractChecked: readTree() !== null };
 }
 
 function main() {
-  const { found, stale, unreadable, wrote, unattributable, empty, contractChecked } = checkAll();
+  const { found, stale, unreadable, wrote, unattributable, neighbours, empty, contractChecked } = checkAll();
   if (empty) {
     console.error("generated-files-are-current: no scripts/mint-*.mjs found. Either they moved or the "
       + "naming changed — and a pass over nothing is not a pass.");
@@ -154,6 +179,12 @@ function main() {
   console.log(`\ngenerated-files-are-current: checked ${found.length} minter(s)`
     + (contractChecked ? "" : "; the tree could not be read, so nothing verified that `--check` changed nothing"));
 
+  // NAMED, NOT FAILED: the file, and that the writer was not the minter. The fix belongs to whatever
+  // wrote inside the checkout, and the wrapper's own no-writes check is the one that fails it.
+  for (const { m, moved } of neighbours ?? []) {
+    console.error(`\nnot ${m}: another process wrote ${moved.join(", ")} inside the checkout while it ran — `
+      + `untracked, so not a generated file; this check's answers stand.`);
+  }
   for (const { m, out } of [...wrote, ...stale, ...unreadable]) {
     console.error(`\n──── ${m} ────\n${out}`);
   }

package/scripts/live-surface-check.mjs

@@ -11,14 +11,14 @@
 // because none of them is a property of the source — they are properties of the PROCESSES that are
 // running, the ENVIRONMENT they were started in, and the COMMIT they were started from:
 //
-//   • #98 — the ops-MCP told every caller that three of five depths were "not switched on". They were
+//   • THE AVAILABILITY MISMATCH — the ops-MCP told every caller that three of five depths were "not switched on". They were
 //     switched on; the portal said so on the same box at the same moment. The MCP unit had no
 //     EnvironmentFile, so it read availability from an environment it did not have. The validation that
 //     was supposed to catch this ran `describe_options` in a plain shell — the one environment that
 //     makes it dishonest — and reported 10/10. A probe that talks to the RUNNING service cannot make
 //     that mistake.
 //
-//   • #83 — the ops-MCP had no CLEAROTRON_CUSTOMERS_DIR, silently fell back to the bundled demo roster, and
+//   • THE ROSTER FALLBACK — the ops-MCP had no CLEAROTRON_CUSTOMERS_DIR, silently fell back to the bundled demo roster, and
 //     refused every real customer. Nothing anywhere compared the roster a door resolves against the
 //     roster on disk.
 //
@@ -35,7 +35,7 @@
 // Stated plainly, because a check that quietly skips a surface is worse than one that says it did:
 //
 //   ops-MCP      loopback, TRADEMARK_MCP_AUTH_DISABLED — fully reachable, two independent code paths
-//                (describe_options → lib/options.mjs, plan_run → lib/plan.mjs). #98 lived in BOTH, so
+//                (describe_options → lib/options.mjs, plan_run → lib/plan.mjs). The availability mismatch lived in BOTH, so
 //                comparing them to each other is necessary but NOT sufficient…
 //   on-disk      …which is why the load-bearing comparison is against the flag snapshot, recomputed
 //                here through the ENGINE's own productAvailability(). That is the source of truth the
@@ -47,10 +47,10 @@
 //
 // ── it must call the doors AS A REAL CALLER DOES ─────────────────────────────────────────────────────
 //
-// Learned while writing this, and worth stating because it is the same trap as #98 wearing a different
+// Learned while writing this, and worth stating because it is the same trap as the availability mismatch wearing a different
 // hat. A token-less loopback call to the ops face initialises an accounts-scoped session with NO
 // accounts: `list_profiles` answers `clients: 0` and `plan_run` refuses, because an empty grant covers
-// no account and not the neutral profile either. The first version of this script read that as a live #83 and was
+// no account and not the neutral profile either. The first version of this script read that as a live roster fallback and was
 // WRONG — the deployment was fine; the caller was not. With the portal's own ops token the same call
 // answers `clients: 10`.
 //
@@ -97,7 +97,7 @@ import { treeOfRunning } from "../shared/checkout-move.mjs";           // …and
 import { findUnitFiles, unitFilePath } from "../driver/unit-files.mjs";   //
 import { managerGroupsVerdict } from "../driver/manager-groups-verdict.mjs";   //
 import { config } from "../driver/driver.config.mjs";                          //
-import { probeQueueWatch, probeWorker, probeTimer } from "../driver/queue-watch-probe.mjs";   // · and, tracker issue 206, the units that say HOW this box drains
+import { probeQueueWatch, probeWorker, probeTimer } from "../driver/queue-watch-probe.mjs";   // · and the units that say HOW this box drains
 import { doorPostureVerdict } from "../mcp-server/door-posture.mjs";   // — a door whose mode came from another door's variables
 import { readDrainerStamp, drainerVerdict, defaultPpidOf } from "../driver/drainer-identity.mjs";   // — the process that EXECUTES runs
 import { readUpdaterStamp, updaterVerdict, resolveUpdaterStampPath, updaterAbsentHere, UPDATER_STAMP_BASENAME } from "../driver/updater-identity.mjs";   // — the mechanism that PLACES commits
@@ -105,7 +105,7 @@ import { claimerIsAlive } from "../driver/claim-liveness.mjs";
 import { processTable } from "../shared/process-table.mjs";                          // — /proc is not the only box
 import { envFrom } from "../shared/env-aliases.mjs";
 import { gitTry, treeOf } from "../shared/tree-commit.mjs";   // — a packaged install has no git, and says its commit in build-info.json
-import { exitFor } from "../driver/surface-exit-verdict.mjs";   // — a could-not-look is not a drift, and they want different things done   // — the name a reader is told to set is the one in force
+import { exitFor } from "../driver/surface-exit-verdict.mjs";   // — a check that could not look is not a drift, and they want different things done   // — the name a reader is told to set is the one in force
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const asJson = process.argv.includes("--json");
@@ -170,12 +170,12 @@ const PORTAL_URL = DOORS.portal.url;
 const CLIENT_MCP_URL = DOORS["client door"].url;
 
 // The bundled demo roster, as `list_profiles` REPORTS it. A door that resolves exactly this set is a
-// door with no CLEAROTRON_CUSTOMERS_DIR — #83. Compared as a set, not a count: a deployment may legitimately
+// door with no CLEAROTRON_CUSTOMERS_DIR — the roster fallback. Compared as a set, not a count: a deployment may legitimately
 // have three customers.
 //
 // DERIVED FROM THE DIRECTORY THAT SHIPS IT, never written down here. As a hand-maintained triple this
 // went stale the day a fourth bundle landed: the set-equality could no longer match anything, so the
-// #83 detector returned PASS on the #83 condition — a guard that cannot match reports that it found
+// roster-fallback detector returned PASS on the roster fallback itself — a guard that cannot match reports that it found
 // nothing wrong. The two earlier faults on this same constant failed CLOSED and someone investigated;
 // this one failed open. `generic` is excluded by the derivation, because `list_profiles` reports it as
 // `genericFallback` rather than as a member of `clients[]`.
@@ -203,7 +203,7 @@ const skip = (n, d) => record(n, "skip", d);   // could not be reached — never
  * Two arms used to call `fail` while their own message said "This is a failure to look, never a pass".
  * The text was honest and the verdict was not: FAIL is what a genuine drift also produces, so a reader
  * could not tell "this box has drifted" from "I was unable to look" without reading to the end of the
- * message. A drift is fixed by redeploying; a could-not-look is fixed by pointing the check at something
+ * message. A drift is fixed by redeploying; a check that could not look is fixed by pointing the check at something
  * it can read. Until somebody does, nothing is known either way.
  *
  * IT IS NOT THE SAME AS AN ORDINARY SKIP, which is why this exists rather than reusing `skip`. Several
@@ -536,7 +536,7 @@ const wiredRegister = snapshot?.register?.provider ?? null;
 if (wiredRegister) pass("register wired", `${wiredRegister} · canCount=${snapshot.register?.canCount === true}`);
 else skip("register wired", "the snapshot carries no register block");
 
-// 3a. The roster a door RESOLVES, vs the roster on disk. #83: no CLEAROTRON_CUSTOMERS_DIR ⇒ the bundled demos
+// 3a. The roster a door RESOLVES, vs the roster on disk. The roster fallback: no CLEAROTRON_CUSTOMERS_DIR ⇒ the bundled demos
 //     ⇒ every real customer refused. Counts and set-identity only — never a customer name.
 //     Runs BEFORE the availability checks because plan_run needs a profile to plan against, and taking
 //     it from what the door itself resolved is what keeps a customer key out of this source file.
@@ -561,7 +561,7 @@ try {
   //   clients: 0        → an accounts-scoped session with NO accounts, i.e. THIS CALLER is unscoped.
   //                       A statement about the probe, not the deployment. Never a failure.
   //   clients: <demos>  → the door resolved the BUNDLED roster, i.e. CLEAROTRON_CUSTOMERS_DIR is not reaching
-  //                       the service. A statement about the deployment. This is #83.
+  //                       the service. A statement about the deployment. This is the roster fallback.
   // On the TEST instance the bundled roster is the CORRECT answer — CLEAROTRON_CUSTOMERS_DIR is deliberately
   // unset there so real client bundles never reach it. Same observation, opposite verdict, so the
   // instance has to say which it is rather than the check guessing from a hostname or a path.
@@ -570,10 +570,10 @@ try {
   // protected; inside this top-level-await script neither could be caught by a test.
   // The derivation THROWS rather than handing back an empty set, and the throw is caught here on its own
   // so it cannot be reported as a list_profiles fault. Either way it is never a pass: an unreadable
-  // profiles directory means #83 cannot be ruled out, which is a could-not-look and says so.
+  // profiles directory means the roster fallback cannot be ruled out: the check could not look, and says so.
   let bundledDemos = null;
   try { bundledDemos = bundledDemoKeys({ profilesDir: BUNDLED_PROFILES_DIR }); }
-  catch (e) { fail("roster resolves", `the bundled roster could not be derived, so #83 cannot be ruled out: ${e.message}`); }
+  catch (e) { fail("roster resolves", `the bundled roster could not be derived, so a door falling back to the bundled demo roster cannot be ruled out: ${e.message}`); }
 
   // THE DOOR ANSWERED FOR THIS KEY, so the comparison is made within this key's cap. Its claims are read
   // the way doctor and the brand-owner command read them. A key that cannot be read leaves the verdict
@@ -608,7 +608,7 @@ try {
 }
 
 // 3. THE LOAD-BEARING CHECK — every door's availability answer vs the engine's own, recomputed here
-//    from the snapshot. This is #98: the MCP disagreed with the portal because it derived availability
+//    from the snapshot. This is the availability mismatch: the MCP disagreed with the portal because it derived availability
 //    from its own process environment instead of from this file.
 let mcpOptions = null;
 try {
@@ -731,7 +731,7 @@ if (mcpOptions && built) {
   else pass("doors agree with the engine on product availability", `${seen.length} products, all matching: ${seen.join(", ")}`);
 
   // 3b. describe_options and plan_run are two independent code paths (lib/options.mjs, lib/plan.mjs).
-  //     #98 lived in both, so agreement here is necessary-but-not-sufficient — 3 above is the real test.
+  //     The availability mismatch lived in both, so agreement here is necessary-but-not-sufficient — 3 above is the real test.
   //
   //     plan_run needs an explicit profileKey: an accounts-scoped session refuses without one. The key
   //     comes from what the door ITSELF resolved (below), so no customer is ever hardcoded here.
@@ -863,7 +863,7 @@ else {
       // to an unprobed posture — a failure to look, never a pass.
       posture: { worker: probeWorker(), timer: probeTimer() },
     });
-    // — AND THE VERDICT'S OWN could-not-look MARKER, carried through. The verdict distinguishes a
+    // — AND THE VERDICT'S OWN MARKER FOR A CHECK THAT COULD NOT LOOK, carried through. The verdict distinguishes a
     // process table it could not read from one that answered; dropping that here would put the
     // distinction back where it was, one layer down.
     record("the process that executes runs is on the deployed commit", v.state, v.message, v.blocked === true);

package/scripts/release-code-scanning-check.mjs

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// release-code-scanning-check.mjs — is the commit about to be published as a stable one code scanning
+// has finished reading, with nothing left open?
+//
+//   node scripts/release-code-scanning-check.mjs --sha <commit> --repo <owner/name>
+//        [--ref refs/heads/main] [--timeout 1200] [--interval 30]
+//
+// Exit 0: code scanning has a completed analysis of <sha> for every language it analyses on <ref>, and
+// no alert on <ref> is open. Exit 1: alerts are open (each named), or the analysis of <sha> did not arrive
+// within the bound. Exit 2: could not look — the API refused, or the arguments were incomplete.
+//
+// ── WHY A STABLE, AND ONLY A STABLE ─────────────────────────────────────────────────────────────────
+//
+// Code scanning was on and reported alerts, and an integration merge landed with its check red: a scanner
+// that can stay red without stopping anything is a notification. The owner's ruling (2026-09-18): the
+// check is required on main, and a stable is published only over a clean result. Betas are not gated —
+// they are how a fix reaches the people testing it. There is NO OVERRIDE: an open alert is fixed, or
+// dismissed on the alert with a written reason, and then this passes.
+//
+// ── IT WAITS, BECAUSE THE ANALYSIS FOLLOWS THE MERGE ────────────────────────────────────────────────
+//
+// The commit a stable publishes is the version commit, and the version pull request merges itself
+// moments before this runs; code scanning analyses that push in a few minutes (measured on the beta.10
+// release commit: under five). So an analysis not there YET is waited for, bounded; an analysis never
+// there fails the publish, because a verdict nobody reached is not a clean one.
+//
+// ── WHY THE OPEN ALERTS ARE READ ON THE BRANCH ──────────────────────────────────────────────────────
+//
+// Alerts belong to a ref, not to a commit: the open list for main describes main's latest analysis. So
+// the check first requires that analysis to be of <sha> itself — if main has moved past the commit being
+// published, the list describes a different tree and this refuses rather than answer about it.
+import { execFileSync } from "node:child_process";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const arg = (argv, flag, dflt = null) => { const i = argv.indexOf(flag); return i === -1 ? dflt : argv[i + 1]; };
+const sleep = (ms) => new Promise((ok) => setTimeout(ok, ms));
+
+/** `gh api` as JSON, paginated where asked. Throws on a refusal, which the caller turns into exit 2. */
+function gh(path, { paginate = false } = {}) {
+  // Paginated pages come back as one element per line (`--jq '.[]'`), so no page boundary is ever
+  // reassembled by editing text.
+  const args = ["api", ...(paginate ? ["--paginate", "--jq", ".[]"] : []), path];
+  const out = execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1 << 26 });
+  return paginate ? out.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l)) : JSON.parse(out);
+}
+
+/**
+ * PURE. The verdict from what the API said.
+ * @param {object} o
+ * @param {Array<{commit_sha:string, category?:string, error?:string, created_at?:string}>} o.analyses  on <ref>, newest first
+ * @param {Array<{number:number, rule?:{id?:string}, most_recent_instance?:{location?:{path?:string, start_line?:number}}}>} o.open
+ */
+export function verdict({ sha, analyses, open }) {
+  const categories = [...new Set(analyses.map((a) => a.category ?? ""))];
+  if (!categories.length) return { state: "waiting", why: "code scanning has no analysis on this branch at all" };
+  const newest = new Map();
+  for (const a of analyses) if (!newest.has(a.category ?? "")) newest.set(a.category ?? "", a);
+  const notYet = categories.filter((c) => newest.get(c).commit_sha !== sha);
+  if (notYet.length) {
+    const moved = notYet.filter((c) => analyses.some((a) => (a.category ?? "") === c && a.commit_sha === sha));
+    if (moved.length) return { state: "moved", why: `the branch's newest ${moved.join(", ")} analysis is of another commit, so its alerts describe a different tree` };
+    return { state: "waiting", why: `no analysis of ${sha.slice(0, 8)} yet for ${notYet.join(", ")}` };
+  }
+  const failed = categories.filter((c) => newest.get(c).error);
+  if (failed.length) return { state: "failed", why: `the analysis of ${sha.slice(0, 8)} for ${failed.join(", ")} reported an error: ${newest.get(failed[0]).error}` };
+  if (open.length) return { state: "open", why: `${open.length} alert(s) are open`, open };
+  return { state: "clean", why: `${categories.length} analysis categor${categories.length === 1 ? "y" : "ies"} of ${sha.slice(0, 8)} complete, no alert open` };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const sha = arg(argv, "--sha"), repo = arg(argv, "--repo");
+  const ref = arg(argv, "--ref", "refs/heads/main");
+  const timeoutSec = Number(arg(argv, "--timeout", "1200")), intervalSec = Number(arg(argv, "--interval", "30"));
+  if (!/^[0-9a-f]{40}$/.test(sha ?? "") || !/^[\w.-]+\/[\w.-]+$/.test(repo ?? "") || !(intervalSec > 0) || !Number.isFinite(timeoutSec)) {
+    console.error("release-code-scanning-check: needs --sha <40-character commit> and --repo <owner/name>. Could not look.");
+    process.exit(2);
+  }
+  const deadline = Date.now() + timeoutSec * 1000;
+  for (;;) {
+    let v;
+    try {
+      const analyses = gh(`repos/${repo}/code-scanning/analyses?ref=${encodeURIComponent(ref)}&tool_name=CodeQL&per_page=100`);
+      const open = gh(`repos/${repo}/code-scanning/alerts?ref=${encodeURIComponent(ref)}&state=open&per_page=100`, { paginate: true });
+      v = verdict({ sha, analyses, open });
+    } catch (e) {
+      console.error(`release-code-scanning-check: the code-scanning API could not be read: ${String(e.stderr ?? e.message).split("\n")[0]}. `
+        + "Could not look, which is not a clean scan.");
+      process.exit(2);
+    }
+    console.log(`release-code-scanning-check: at ${Math.floor(Date.now() / 1000)} — ${v.why}.`);
+    if (v.state === "clean") return;
+    if (v.state === "open") {
+      console.error(`\nA stable is not published over open code-scanning alerts. Fix each, or dismiss it on the alert with a written reason:`);
+      for (const a of v.open.slice(0, 25)) {
+        const l = a.most_recent_instance?.location ?? {};
+        console.error(`  #${a.number}  ${a.rule?.id ?? "?"}  ${l.path ?? "?"}:${l.start_line ?? "?"}`);
+      }
+      if (v.open.length > 25) console.error(`  … and ${v.open.length - 25} more`);
+      process.exit(1);
+    }
+    if (v.state === "moved" || v.state === "failed") { console.error(`\nrelease-code-scanning-check: ${v.why}. Not published.`); process.exit(1); }
+    if (Date.now() + intervalSec * 1000 > deadline) {
+      console.error(`\nrelease-code-scanning-check: after ${timeoutSec}s, ${v.why}. A verdict nobody reached is not a `
+        + "clean one, so the stable is not published. Re-run the job once the analysis has finished.");
+      process.exit(1);
+    }
+    await sleep(intervalSec * 1000);
+  }
+}
+
+if (isEntrypoint(import.meta.url)) main();

package/scripts/release-visible-check.mjs

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// release-visible-check.mjs — can a stranger's npm client get the version this run just published?
+//
+//   node scripts/release-visible-check.mjs --version <v> --tag <dist-tag> --tarball <file>
+//        [--timeout 900] [--interval 15] [--registry https://registry.npmjs.org] [--name clearotron]
+//
+// Exit 0: the registry serves <v>, the <dist-tag> names it, and the tarball it serves is byte for byte
+// the one at <file> — the bytes this run published. Exit 1: not within the bound, or the registry serves
+// different bytes; the caller creates no release entry. Exit 2: could not look — bad arguments, or the
+// local tarball cannot be read.
+//
+// ── WHY THIS RUNS BEFORE THE RELEASE ENTRY ─────────────────────────────────────────────────────────
+//
+// `npm publish` returning is the registry accepting the upload, not the registry serving it. Measured on
+// 0.3.2-beta.10, 2026-09-18: the release entry went up at 19:47:40Z and the workflow finished three
+// seconds later, while an unauthenticated `npm view clearotron@0.3.2-beta.10` answered E404 and the beta
+// tag still named beta.9 until about 19:56Z. Nine minutes in which the releases page named a version
+// nobody could install, and a green run reported it done on evidence no user could see. So the entry
+// waits for the registry to answer a stranger, and a registry that never does leaves no entry at all.
+//
+// ── UNAUTHENTICATED ON PURPOSE ──────────────────────────────────────────────────────────────────────
+//
+// Plain requests with no credential and no npm configuration. The publishing job holds a publish
+// credential, and a read made with it can see what the public cannot yet — which is the gap this
+// exists to close. No cache-busting query either: a stranger's client does not add one.
+//
+// ── AND THE BYTES, NOT ONLY THE NAME ────────────────────────────────────────────────────────────────
+//
+// A version document can answer while the tarball behind it is not the one this run built. So the
+// tarball the registry serves is fetched, as `npm pack <name>@<version>` would fetch it, and its sha512
+// is compared both with the registry's own recorded integrity and with the local file this run
+// uploaded. Either disagreeing is a refusal, not a warning.
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const arg = (argv, flag, dflt = null) => { const i = argv.indexOf(flag); return i === -1 ? dflt : argv[i + 1]; };
+const sri = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+const sleep = (ms) => new Promise((ok) => setTimeout(ok, ms));
+
+/** One look at the registry, as a stranger. Returns what it served and nothing it did not. */
+export async function lookOnce({ registry, name, version, tag }) {
+  const seen = { version: null, tagged: null, integrity: null, tarball: null, error: null };
+  try {
+    const v = await fetch(`${registry}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`, { headers: { accept: "application/json" } });
+    if (v.ok) {
+      const doc = await v.json();
+      seen.version = doc.version ?? null;
+      seen.integrity = doc.dist?.integrity ?? null;
+      seen.tarball = doc.dist?.tarball ?? null;
+    }
+    const t = await fetch(`${registry}/-/package/${encodeURIComponent(name)}/dist-tags`, { headers: { accept: "application/json" } });
+    if (t.ok) seen.tagged = (await t.json())?.[tag] ?? null;
+  } catch (e) { seen.error = String(e?.message ?? e); }
+  return seen;
+}
+
+/** PURE. Is what a look saw the published version, under its tag? */
+export function visible(seen, { version }) {
+  return seen.version === version && seen.tagged === version && typeof seen.tarball === "string";
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const version = arg(argv, "--version"), tag = arg(argv, "--tag"), tarballPath = arg(argv, "--tarball");
+  const registry = String(arg(argv, "--registry", "https://registry.npmjs.org")).replace(/\/+$/, "");
+  const name = arg(argv, "--name", "clearotron");
+  const timeoutSec = Number(arg(argv, "--timeout", "900")), intervalSec = Number(arg(argv, "--interval", "15"));
+  if (!version || !tag || !tarballPath || !Number.isFinite(timeoutSec) || !Number.isFinite(intervalSec) || intervalSec <= 0) {
+    console.error("release-visible-check: needs --version, --tag and --tarball, and a positive --interval. Could not look.");
+    process.exit(2);
+  }
+  let local;
+  try { local = sri(readFileSync(tarballPath)); }
+  catch (e) { console.error(`release-visible-check: cannot read the published tarball ${tarballPath}: ${e.message}. Could not look.`); process.exit(2); }
+
+  const started = Date.now(), deadline = started + timeoutSec * 1000;
+  const epoch = () => Math.floor(Date.now() / 1000);
+  let seen;
+  for (;;) {
+    seen = await lookOnce({ registry, name, version, tag });
+    const waited = Math.round((Date.now() - started) / 1000);
+    console.log(`release-visible-check: at ${epoch()} (+${waited}s) the registry answers ${name}@${version} → `
+      + `${seen.version ?? "nothing"}; ${tag} → ${seen.tagged ?? "nothing"}${seen.error ? ` (${seen.error})` : ""}`);
+    if (visible(seen, { version })) break;
+    if (Date.now() + intervalSec * 1000 > deadline) {
+      console.error(`\nrelease-visible-check: after ${waited}s an unauthenticated client still cannot get ${name}@${version} `
+        + `under \`${tag}\`. The publish was accepted and is not yet served, so no release entry is created: `
+        + "the page would name a version nobody can install. The tag is already written, so the pipeline "
+        + "knows this version is published; re-run this job to create the entry once the registry serves it.");
+      process.exit(1);
+    }
+    await sleep(intervalSec * 1000);
+  }
+
+  let served;
+  try {
+    const r = await fetch(seen.tarball);
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    served = sri(Buffer.from(await r.arrayBuffer()));
+  } catch (e) {
+    console.error(`release-visible-check: the registry names ${seen.tarball} and it could not be fetched: ${e.message}. No release entry.`);
+    process.exit(1);
+  }
+  if (served !== local || (seen.integrity && seen.integrity !== local)) {
+    console.error(`release-visible-check: the registry serves DIFFERENT BYTES for ${name}@${version}.\n`
+      + `  published by this run: ${local}\n  served:                ${served}\n  recorded integrity:    ${seen.integrity ?? "none"}\n`
+      + "No release entry is created for a version whose install is not the build this run verified.");
+    process.exit(1);
+  }
+  console.log(`release-visible-check: a stranger can install ${name}@${version} under \`${tag}\`, `
+    + `and the tarball served is the one this run published (${served.slice(0, 22)}…).`);
+}
+
+if (isEntrypoint(import.meta.url)) main();

package/shared/invocation.mjs

@@ -141,8 +141,8 @@ export function installRoute(dir = INSTALL_DIR) {
  *     <prefix>/lib/node_modules/clearotron      ← this module's install directory
  *     <prefix>/bin/clearotron                   ← the executable npm links for it
  *
- * Measured on the reporter's box: `/home/hardening-b/.npm-global/lib/node_modules/clearotron` and
- * `/home/hardening-b/.npm-global/bin/clearotron`. A LOCAL install — `<project>/node_modules/clearotron`,
+ * Measured on a reader's machine: `/home/<you>/.npm-global/lib/node_modules/clearotron` and
+ * `/home/<you>/.npm-global/bin/clearotron`. A LOCAL install — `<project>/node_modules/clearotron`,
  * no `lib` segment — is deliberately NOT matched: npm links those into `<project>/node_modules/.bin`,
  * which is not on anybody's PATH, and `standFrom` already gives that case its correct answer.
  *

package/shared/register-selection.mjs

@@ -40,6 +40,9 @@ import {
   USPTO_ARCHIVE_GB, USPTO_INDEX_GB, USPTO_INGEST_GB_PER_HOUR, USPTO_DAILY_TOPUP_MB,
   usptoBuildHours, usptoProvisionGB,
 } from "./uspto-index-size.mjs";
+// THE BUILD COMMAND AS THIS INSTALL IS REACHED. It named `npm run sync:uspto`, a script only a checkout has,
+// so a reader who installed the package was handed a command with nothing behind it.
+import { reachableCommand } from "./invocation.mjs";
 
 const SIGNA_SIGNUP = [
   "1. Create an account at https://signa.so/ and open the API section — it is self-serve: no sales",
@@ -64,7 +67,7 @@ const USPTO_WARNINGS = [
   `  · provision ~${usptoProvisionGB()} GB free — the archives are deleted as they are ingested, so they never all exist at once`,
   "The EU register needs NONE of this and works as soon as your EUIPO credentials are in.",
   "A USPTO API key needs an ID.me identity verification, which is a real-world identity check.",
-  "Build it with:  npm run sync:uspto      (resumable — an interrupted build picks up where it stopped)",
+  `Build it with:  ${reachableCommand("sync")}      (resumable — an interrupted build picks up where it stopped)`,
 ];
 
 

package/shared/root-doc-commands.mjs

@@ -20,7 +20,8 @@
 // A bare `clearotron <command>` is command-not-found (exit 127, measured on a real clone) unless the
 // document has already put the binary on `PATH`. Two ways it can have done that:
 //
-//   · an `npm install -g clearotron` line ABOVE the site — line-based, because a reader executing a
+//   · an install line ABOVE the site — `npm install -g clearotron`, or `npx clearotron install` (either
+//     channel), which places the command in `~/.local/bin` — line-based, because a reader executing a
 //     quickstart top to bottom has not run a later line yet;
 //   · the paragraph is ABOUT the `PATH` shim `clearotron install` writes, where the short form is the
 //     thing being explained and `npx` would make the document contradict itself.
@@ -32,8 +33,13 @@
 export const BARE = /(?<!npx )\bclearotron (?=[a-z])/;
 /** The form that works from a fresh clone, and the anti-vacuity signal that the scan is reading. */
 export const NPX = /npx clearotron [a-z]/g;
-/** The line that puts the binary on `PATH` for everything below it. */
-export const GLOBAL_INSTALL = /npm install -g clearotron/;
+/**
+ * The line that puts the binary on `PATH` for everything below it. `npx clearotron install` counts as well
+ * as npm's global form: after it, every documented command uses the launcher it installed rather than a
+ * fresh `npx`, which resolves whichever channel npm picks at that moment — the stable, for a reader who
+ * installed the beta (owner ruling, 2026-09-18).
+ */
+export const GLOBAL_INSTALL = /npm install -g clearotron|npx clearotron(?:@[\w.-]+)? install\b/;
 /** The paragraph that is ABOUT the shim, where the short form is the point. */
 export const SHIM_PARAGRAPH = /short form|on your `PATH`|stop typing/;
 
@@ -81,5 +87,5 @@ export function unreachableBareSites(docs) {
 export function sentenceFor(s) {
   return `${s.file}:${s.line} uses the bare \`clearotron\` form with nothing above it that put the binary `
     + "on `PATH`. For a reader who cloned, that is command-not-found (exit 127, measured) — either write "
-    + "it as `npx clearotron`, or give the document an `npm install -g clearotron` line before this point.";
+    + "it as `npx clearotron`, or give the document an install line before this point.";
 }

package/shared/scope.mjs

@@ -874,8 +874,8 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
 //
 // buildJob REQUIRES a forwarder ("…the requester/reply-routing key that rides the delivery packet
 // (docs/DELIVERY.md)") and plan_run builds the same job start_run does, so a preview without one died on
-// a message naming an internal doc — on the FREE call every connecting principal makes first. #53 fixed
-// that for the account branch only; ops and internal hit the same wall. Fixed here rather than in
+// a message naming an internal doc — on the FREE call every connecting principal makes first. The first fix
+// covered the account branch only; ops and internal hit the same wall. Fixed here rather than in
 // buildJob because the answer is the SESSION's: who is asking is a fact of the verified identity.
 //
 // `args.forwarder ||` first: ops and internal are trusted principals routing on someone else's behalf (an