clearotron 0.3.0-beta.9 → 0.3.0

package/INSTALL.md

@@ -295,6 +295,71 @@ keeps working throughout.
 provider, so it is safe to run on any machine that has the repository. "Safe anywhere" is about spend,
 not about where it will run — on a packaged tree it refuses, as above.
 
+## 2a. Removing it
+
+An install is not one directory, so removing it is not one command. Everything it writes is listed here.
+Read the list before you delete anything: one of these directories holds your reports.
+
+**Stop it first.** If the product is running in a terminal, Ctrl-C in that terminal. If you installed the
+background services, `clearotron stop` stops them and removes their unit files. `clearotron status` says
+which of the two you have.
+
+**The program.** Installed globally, `npm rm -g clearotron` removes it. Installed by `clearotron install`
+(which is also what a demo run from `npx` leaves behind), it lives in two places under `~/.local`:
+
+```
+~/.local/lib/node_modules/clearotron
+~/.local/bin/clearotron
+```
+
+**The settings, and the keys.** `~/.config/clearotron/.env` holds this install's signing secrets, so
+deleting it invalidates every key it ever issued. Beside it: `~/.config/clearotron/token-denylist`, the
+list of keys you revoked, and `~/.config/clearotron/running`, which records a product running in a
+terminal and is rewritten on every start.
+
+**Your work.** The install keeps it all under one directory, `~/trademark` by default — wherever
+`CLEAROTRON_REPORTS_DIR`'s parent points if you moved it:
+
+```
+~/trademark/pool                              THE REPORTS. Every clearance this install delivered.
+~/trademark/workspace                         the working files of each run, including unfinished ones
+~/trademark/queue                             work ordered and not yet run
+~/trademark/outbox                            what the product prepared to send
+~/trademark/locks                             which runs are in flight
+~/trademark/config                            your companies, their projects and your saved searches
+~/trademark/config/recipes                    the saved searches themselves
+~/trademark/config/profiles                   the company profiles
+~/trademark/grants.json                       who may use this install
+~/trademark/portal-audit.log                  what the portal was asked to do
+~/trademark/portal-local-credential.json      the sign-in this install minted for you
+```
+
+**Keep the pool if you want the reports.** They are finished documents and nothing else reads them: move
+`~/trademark/pool` somewhere of your own and delete the rest. Deleting the pool deletes the clearances.
+
+**The demo, if you ran one.** `~/trademark-demo` holds the demo's own copy of everything above, including
+its own copy of the program under `~/trademark-demo/program`. It is one directory to remove and it shares
+nothing with an install.
+
+**The background services, if you installed them.** `clearotron stop` removes the four unit files; if you
+would rather see them, they are in `~/.config/systemd/user`:
+
+```
+clearotron-portal.service
+clearotron-mcp-face.service
+clearotron-worker.service
+clearotron-client-mcp.service
+```
+
+**And `~/.env`, which only a background install writes.** A service inherits nothing from the terminal
+that installed it, so `clearotron start --background` writes everything those services need into `~/.env`,
+mode 600 — your register credential, your research key and the engine's settings among it. It is not the
+same file as `~/.config/clearotron/.env`, which configures the product when you run it yourself. Delete
+both, or you leave a file of credentials in your home for services that no longer exist.
+
+Nothing else on the machine is ours: no system-wide files, no services outside your own user, and nothing
+in `/etc`, `/usr` or `/var`.
+
 ## 3. Configuration (environment)
 
 Runtime configuration is by environment variable, and there are two ways to supply them.

package/README.md

@@ -59,6 +59,9 @@ npx clearotron@beta install
 What each channel promises, and when a stable is cut: [docs/RELEASES.md](docs/RELEASES.md). If you are not
 sure, the first command is the one you want.
 
+Removing it later: **[INSTALL.md §2a](INSTALL.md#2a-removing-it)** lists every path an install writes, and
+says which one holds your reports so you can keep them deliberately.
+
 ## Quick start
 
 With it installed, check what it found before it does anything. `doctor` only reads — it writes nothing,

package/bin/onboard.mjs

@@ -116,7 +116,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-p
 // one synopsis reader for every verb that prints one.
 import { usageBlock } from "../shared/usage-block.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // — ONE KEY=value reader; a second copy would drift from what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // — ONE KEY=value reader, taken from a leaf: the unit renderer re-exports this same function, and it is a COMMAND, so importing it from here would put a command in this binary's graph
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";   // — F34: claim about the UNITS only from the units' own environment
 
 /**

package/bin/status.mjs

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { BACKGROUND_UNITS, resolvePorts } from "./start.mjs";
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // ONE KEY=value reader — what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader — what systemd actually reads, taken from the leaf the unit renderer re-exports it from
 import { CLIENT_DOOR_UNIT, clientDoorPort } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
 import { readRunning, probe } from "../shared/running-start.mjs";

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "8f26558701f6930799f7d8f724ab2ea91e302103",
-  "version": "0.3.0-beta.9"
+  "commit": "cd86797b655d82bc021e2ada72cbacdc261174dc",
+  "version": "0.3.0"
 }

package/docs/RELEASES.md

@@ -54,5 +54,5 @@ Downgrading is an ordinary install of the older version. Your configuration and
 by either — they live outside the package — so moving between channels is not a migration.
 
 Every version's notes are on the [releases page](https://github.com/CordilleraSarl/clearotron/releases)
-and in `CHANGELOG.md`, grouped New / Fixed / For operators. A beta's notes are the same notes; the stable
+and in `CHANGELOG.md`, grouped Before you upgrade / New / Fixed / For operators. A beta's notes are the same notes; the stable
 that follows aggregates all of them into one entry.

package/driver/CHANGELOG.md

@@ -1,5 +1,39 @@
 # clearotron-driver
 
+## 0.3.0
+
+### Minor Changes
+
+- d2afa5e: Before you upgrade: Name every person who uses your installation in the file that lists who may sign in, or the portal will not start. That file is in your install folder.
+- d2afa5e: New: Switch between companies from any screen, and set a new one up in the browser.
+- d2afa5e: New: Add people from the portal, and give each the right to run clearances, to manage people and companies, or both.
+- d2afa5e: New: Every register finding in a report links to the trade mark office's own page for that record.
+- d2afa5e: New: A clearance records any territory it could not cover, so a partial search never reads as a complete one.
+- d2afa5e: New: Connect Clearotron to your own AI assistant — Claude Code, Codex, or ChatGPT — on your computer or a shared server.
+- d2afa5e: New: A saved search is available in every company, in the portal and in your AI assistant.
+- d2afa5e: New: Check a risk framework for errors before it rates a clearance, and point a company at its own.
+- d2afa5e: New: Group companies under an organisation, each with its own daily limit on clearances.
+- d2afa5e: New: Clearotron installs to a fixed location, so the commands it prints and your AI assistant's connection keep working.
+- d2afa5e: New: `clearotron update` moves an installation, beta included, to the current release.
+
+### Patch Changes
+
+- d2afa5e: Fixed: You sign in, open your companies, and run your first clearance on a new installation.
+- d2afa5e: Fixed: The demo reads and writes only its own companies, reports, and saved searches.
+- d2afa5e: Fixed: `clearotron doctor` checks what a clearance needs, so an installation it clears can run one.
+- d2afa5e: Fixed: A key you paste at a yes-or-no question stays off the screen and out of your command history.
+- d2afa5e: Fixed: Clearotron stays signed in to a paid Codex plan when Codex renews the sign-in.
+- d2afa5e: Fixed: The dashboard shows only the chosen company's clearances, and keeps the filters on screen.
+- d2afa5e: Fixed: The Stop button ends a run before its report goes out, and its dialog says what stopping does.
+- d2afa5e: Fixed: A knockout report names the filings behind each finding, and marks the reviewer's notes as reference.
+
+## 0.3.0-beta.10
+
+### Patch Changes
+
+- fd3a4f7: Fixed: A portal address that does not exist now says so wherever it is. Addresses under the admin path used to show the Global config screen.
+- fd3a4f7: New: The install guide now says how to remove Clearotron, naming every path it writes and which one holds your reports.
+
 ## 0.3.0-beta.9
 
 ### Patch Changes

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.9",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/suite-census.json

@@ -647,7 +647,7 @@
         },
         "a-release-note-is-written-for-its-reader.test.mjs": {
           "tests": 9,
-          "asserts": 63,
+          "asserts": 66,
           "skips": 0,
           "todos": 0
         },
@@ -1319,7 +1319,7 @@
         },
         "client-door.test.mjs": {
           "tests": 38,
-          "asserts": 161,
+          "asserts": 162,
           "skips": 1,
           "todos": 0
         },
@@ -2799,6 +2799,12 @@
           "skips": 0,
           "todos": 0
         },
+        "nothing-a-command-awaits-imports-it-back.test.mjs": {
+          "tests": 16,
+          "asserts": 49,
+          "skips": 0,
+          "todos": 0
+        },
         "numeric-setting-refuses.test.mjs": {
           "tests": 15,
           "asserts": 35,
@@ -4235,7 +4241,7 @@
         },
         "start-refuses-on-a-box-that-has-the-services.test.mjs": {
           "tests": 6,
-          "asserts": 17,
+          "asserts": 20,
           "skips": 0,
           "todos": 0
         },
@@ -4665,6 +4671,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-install-guide-says-how-to-remove-it.test.mjs": {
+          "tests": 4,
+          "asserts": 11,
+          "skips": 0,
+          "todos": 0
+        },
         "the-install-names-the-auth-values-it-needs.test.mjs": {
           "tests": 9,
           "asserts": 25,
@@ -4834,8 +4846,8 @@
           "todos": 0
         },
         "the-published-manifest-is-not-the-repos-manifest.test.mjs": {
-          "tests": 18,
-          "asserts": 65,
+          "tests": 21,
+          "asserts": 82,
           "skips": 1,
           "todos": 0
         },
@@ -5858,8 +5870,8 @@
           "todos": 0
         },
         "nav.test.ts": {
-          "tests": 12,
-          "asserts": 57,
+          "tests": 13,
+          "asserts": 67,
           "skips": 0,
           "todos": 0
         },

package/driver/unit-environment.mjs

@@ -35,7 +35,7 @@
 // PURE. It opens no file and knows no path: the caller injects the unit text and the env-file text, so
 // every branch — including the ones a developer box cannot produce — is drivable from a test.
 
-import { parseEnvFile } from "./systemd/render-units.mjs";
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // the leaf the unit renderer re-exports it from; this module stays free of the command
 
 /** systemd's own name for "load this file, and do not fail if it is missing". */
 const OPTIONAL = "-";

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-artifacts-mcp
 
+## 0.3.0
+
+No changes in this release.
+
+## 0.3.0-beta.10
+
+No changes in this release.
+
 ## 0.3.0-beta.9
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.9",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.0-beta.9",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/dist/assets/{index-qes7gLpM.js → index-CwPAS0we.js}

@@ -11008,7 +11008,8 @@ var NAV = [
 		label: "Clearance",
 		path: "/portal/result",
 		icon: "layers",
-		hidden: true
+		hidden: true,
+		subtree: true
 	},
 	{
 		id: "about",
@@ -11107,7 +11108,7 @@ function avatarMenuFor(who, entries = NAV) {
 }
 function screenForPath(path, who, entries = NAV) {
 	const clean = path.replace(/[?#].*$/, "").replace(/\/+$/, "") || "/portal";
-	const hits = flatten(routableFor(who, entries)).filter((e) => clean === e.path || clean.startsWith(e.path + "/"));
+	const hits = flatten(routableFor(who, entries)).filter((e) => clean === e.path || e.subtree === true && clean.startsWith(e.path + "/"));
 	if (!hits.length) return null;
 	return hits.reduce((a, b) => b.path.length > a.path.length ? b : a);
 }

package/portal-ui/dist/index.html

@@ -49,7 +49,7 @@
     -->
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700,900&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/portal/assets/index-qes7gLpM.js"></script>
+    <script type="module" crossorigin src="/portal/assets/index-CwPAS0we.js"></script>
     <link rel="stylesheet" crossorigin href="/portal/assets/index-Cv-E_agg.css">
   </head>
   <body>

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.9",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0
+
+No changes in this release.
+
+## 0.3.0-beta.10
+
+No changes in this release.
+
 ## 0.3.0-beta.9
 
 No changes in this release.

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.0-beta.9",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/scripts/import-cycle-check.mjs

@@ -0,0 +1,468 @@
+// 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
+//
+// import-cycle-check.mjs — nothing a command awaits may import that command back.
+//
+// THE FAILURE THIS EXISTS FOR, AND WHY NOTHING ELSE CATCHES IT.
+//
+// A module can be both a module and a command. When such a module carries a TOP-LEVEL await, anything it
+// reaches while that await is still settling must not import it back, because the import asks for a module
+// that is mid-evaluation. The request never resolves. Node prints "Detected unsettled top-level await" and
+// names the line of the await — not the import that closed the loop, and not the file that added it.
+//
+// Measured 2026-09-12: one static `import { parseEnvFile } from "../driver/systemd/render-units.mjs"` in
+// `bin/start.mjs` stopped 21 install and unit-placement arms at once. `render-units.mjs --apply` IS the
+// documented server install, so the defect refused to install rather than misbehaving quietly. Lint, the
+// pattern guards, the portal build and the packaged-bytes guard all passed around it; only arms that run
+// the command for real caught it, on the third push.
+//
+// The same shape is already in the tree once: `bin/onboard.mjs` carries a top-level `await runCli()` and
+// reaches `bin/start.mjs` from inside it, so a static import of onboard from start takes `doctor` down.
+// That one had a bespoke arm naming one file pair. This check holds the property for the whole class.
+//
+// WHAT COUNTS AS AN EDGE, AND WHY THE OBVIOUS RULE IS WRONG.
+//
+// A static import always counts: importing a module evaluates it. A DYNAMIC import counts only where it is
+// awaited on the top-level await's own call path — `writeInstallEnv`'s imports are on it; the register
+// table at `bin/start.mjs` and the renderer it fetches when placing units are not, because a dynamic
+// import inside a function closes no load-time loop and both are deliberate.
+//
+// A rule of "no command is imported by a binary" would refuse correct call sites. Following every dynamic
+// import regardless of where it sits reports cycles that do not exist and would demand the repair that
+// CAUSES this bug. Neither is the property. The property is the sentence at the top of this file.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, normalize, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const ROOTS = ["bin", "driver", "shared", "scripts"];
+const SKIP = new Set(["node_modules", ".git", "dist", "coverage"]);
+
+/**
+ * Entry points that carry a top-level await must number at least this many, or the scanner has stopped
+ * recognising its subject. A FLOOR ON THE POPULATION, not on the matches: an empty class reads exactly
+ * like a clean one, and this class is invisible failures by definition.
+ *
+ * SET JUST UNDER WHAT THE TREE CARRIES, which is 18. A floor far below the real count is not a floor:
+ * an earlier draft read brace depth per line, and a floor of 12 would have passed that regression
+ * without a word (found in review).
+ *
+ * IT READ 22 BEFORE, AND THAT NUMBER WAS WRONG — do not restore it. A function whose signature carries
+ * an object-literal default, `async function f(ctx, opts = {}) {`, had its body read as module scope,
+ * so ordinary awaits inside four commands counted as top-level. Each departure was checked rather than
+ * assumed: the awaits in `connect`, `brandowner`, `drain-preflight` and `pool-admin` all sit inside
+ * named functions, and the command `pipeline.mjs` — which this check briefly accused of a cycle — exits
+ * on a usage message rather than hanging. The two that must never leave are here: the unit renderer
+ * (`if (APPLY) … await …`) and the wizard (`await runCli()` in a module-scope else).
+ */
+export const POPULATION_FLOOR = 16;
+
+/** Reached during a top-level await and absent from every live tree. Named, never skipped in silence:
+ *  `cut/` is withheld from the public repository, and `cut-archive` is deliberately not overlaid either,
+ *  so this path resolves nowhere this check will ever run. An absence nobody declared is a could-not-look. */
+export const KNOWN_ABSENT = Object.freeze(["cut/packed-artifact.mjs"]);
+
+/**
+ * Comments, string bodies and regex literals removed, line count preserved, so what remains is code.
+ *
+ * ONE LEFT-TO-RIGHT PASS, NOT A STACK OF REPLACEMENTS. This was five independent regexes, and their
+ * order is what broke it: a `//` inside a string is eaten as a comment, the quote that followed then
+ * pairs with the wrong one, and from there the file is read out of phase. The symptom was this very
+ * scanner reporting ITSELF as awaiting at the top level, off a template in its own error output — the
+ * word `await` inside a template whose opening backtick had been swallowed upstream (found in review by
+ * printing the lines it claimed, rather than reasoning about which construct was to blame).
+ *
+ * Regex literals are blanked too: `/await\s+.../` carries the token `await` between two non-word
+ * characters, and no boundary test on the word alone can tell that from code.
+ */
+export function blank(src) {
+  const text = String(src ?? "");
+  const out = new Array(text.length);
+  // Where a `/` starts a regex rather than divides: after an operator, a comma, an opening bracket, or
+  // nothing at all. Division follows a value — an identifier, a number, or a closing bracket.
+  const regexCanStart = (prev) => prev === "" || "([{,;:=!&|?+-*%~^<>".includes(prev) || /\breturn|typeof|of|in|case\b/.test(prev);
+  let i = 0, lastSignificant = "";
+  const keep = (n) => { for (let k = 0; k < n; k++, i++) out[i] = text[i]; };
+  const hide = (n, ch) => { for (let k = 0; k < n; k++, i++) out[i] = text[i] === "\n" ? "\n" : ch; };
+  while (i < text.length) {
+    const c = text[i], next = text[i + 1];
+    if (c === "/" && next === "/") { let j = i; while (j < text.length && text[j] !== "\n") j++; hide(j - i, " "); continue; }
+    if (c === "/" && next === "*") { let j = i + 2; while (j < text.length && !(text[j] === "*" && text[j + 1] === "/")) j++; hide(Math.min(j + 2, text.length) - i, " "); continue; }
+    if (c === '"' || c === "'") {
+      let j = i + 1; while (j < text.length && text[j] !== c) { if (text[j] === "\\") j++; j++; }
+      hide(Math.min(j + 1, text.length) - i, "_"); lastSignificant = "x"; continue;
+    }
+    if (c === "`") {
+      // A template ends at its own backtick; `${ … }` may hold code, and this blanks that too — nothing
+      // inside a template can open a load-time import, so losing it costs this check nothing.
+      let j = i + 1, depth = 0;
+      while (j < text.length) {
+        if (text[j] === "\\") { j += 2; continue; }
+        if (text[j] === "$" && text[j + 1] === "{") { depth++; j += 2; continue; }
+        if (text[j] === "}" && depth) { depth--; j++; continue; }
+        if (text[j] === "`" && !depth) break;
+        j++;
+      }
+      hide(Math.min(j + 1, text.length) - i, "_"); lastSignificant = "x"; continue;
+    }
+    if (c === "/" && regexCanStart(lastSignificant)) {
+      let j = i + 1, inClass = false, closed = false;
+      while (j < text.length && text[j] !== "\n") {
+        if (text[j] === "\\") { j += 2; continue; }
+        if (text[j] === "[") inClass = true;
+        else if (text[j] === "]") inClass = false;
+        else if (text[j] === "/" && !inClass) { closed = true; break; }
+        j++;
+      }
+      if (closed) { hide(j + 1 - i, "_"); lastSignificant = "x"; continue; }
+    }
+    if (!/\s/.test(c)) lastSignificant = c;
+    keep(1);
+  }
+  return out.join("");
+}
+
+/**
+ * Lines carrying an await with NO function-opened brace around them.
+ *
+ * Depth alone is not the test. `bin/onboard.mjs` awaits inside a module-scope `if`/`else`, which is a
+ * genuine top-level await at brace depth one, and a depth-zero scan would miss the module that proves this
+ * class exists. So each open brace remembers whether the line that opened it looked like a function.
+ */
+/** Blocks that are not functions, so an `await` inside one is still the module's own. */
+const CONTROL = new Set(["if", "for", "while", "switch", "catch", "do", "with", "else", "try", "finally"]);
+
+/**
+ * Did a function open this brace? Read structurally, never by looking back over text.
+ *
+ * A TEXT WINDOW GETS THIS WRONG ON THE COMMONEST IDIOM IN THIS TREE. The first version split the
+ * preceding text on `[;{}]` and asked whether the last piece said `function` — and
+ * `async function runDigest(ctx, opts = {}) {` contains a brace pair IN ITS PARAMETER LIST, so the
+ * window reset and the body brace saw only `) `. Every function with an object-literal default had its
+ * body read as module scope, and `driver/pipeline.mjs` reported 84 top-level awaits that are ordinary
+ * awaits inside functions — a cycle the check then claimed on a tree that runs perfectly (found by
+ * driving the command it named: it exits 2 on a usage message, not 13 on a hang).
+ *
+ * So: step over the parameter list by matching parentheses, then read the name in front of it.
+ */
+export function opensFunction(text, at) {
+  let j = at - 1;
+  const skipSpace = () => { while (j >= 0 && /\s/.test(text[j])) j--; };
+  skipSpace();
+  if (j >= 1 && text[j] === ">" && text[j - 1] === "=") return true;          // `=> {`
+  if (j >= 0 && text[j] === ")") {
+    let depth = 0;
+    for (; j >= 0; j--) {
+      if (text[j] === ")") depth++;
+      else if (text[j] === "(") { depth--; if (!depth) break; }
+    }
+    j--; skipSpace();
+    let end = j;
+    while (j >= 0 && /[\w$]/.test(text[j])) j--;
+    const name = text.slice(j + 1, end + 1);
+    return !CONTROL.has(name);                                                // `f(…) {` but not `if (…) {`
+  }
+  let k = j, word = "";
+  while (k >= 0 && /[\w$]/.test(text[k])) { word = text[k] + word; k--; }
+  return word === "class" || (word !== "" && !CONTROL.has(word) && /\bclass\b/.test(text.slice(Math.max(0, k - 20), k + 1)));
+}
+
+export function topLevelAwaitLines(src) {
+  const text = blank(src);
+  const opened = [];
+  const hits = new Set();
+  let line = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\n") { line++; continue; }
+    if (ch === "{") { opened.push(opensFunction(text, i)); continue; }
+    if (ch === "}") { opened.pop(); continue; }
+    // THE TOKEN, NOT THE WORD. `blank()` removes comments and string bodies but not regex literals, and
+    // this very file carries `/await\s+([A-Za-z_$][\w$]*)\s*\(/` — which has `await` between two
+    // non-word characters, so a boundary test alone counted this scanner as awaiting at its own top
+    // level (found in review by reading the population it reported). A real `await` is followed by
+    // whitespace or an open parenthesis; inside that regex it is followed by a backslash.
+    if (ch === "a" && text.startsWith("await", i) && !/[\w$/\\]/.test(text[i - 1] ?? " ") && /[\s(]/.test(text[i + 5] ?? "")) {
+      if (!opened.some(Boolean)) hits.add(line);
+    }
+  }
+  return [...hits];
+}
+
+/** The whole argument expression of every `import(...)`, parentheses counted rather than split on a comma. */
+export function importArguments(text) {
+  const src = String(text ?? "");
+  const out = [];
+  for (const m of src.matchAll(/\bimport\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    let depth = 0;
+    for (let j = open; j < src.length; j++) {
+      const c = src[j];
+      if (c === "(") depth++;
+      else if (c === ")") { depth--; if (!depth) { out.push(src.slice(open + 1, j)); break; } }
+    }
+  }
+  return out;
+}
+
+/**
+ * The literal chunks of a specifier, whatever shape it is written in.
+ *
+ * THREE SHAPES, AND A READER THAT KNOWS ONLY THE FIRST IS BLIND TO THE CASE THAT BIT US. `bin/onboard.mjs`
+ * reaches `bin/start.mjs` through `pathToFileURL(join(REPO, "bin", "start.mjs")).href` — computed, not
+ * quoted. A literal-only scan finds nothing there and reports a complete walk. An argument yielding no
+ * fragment at all is neither safe nor a specifier this check understood: it is reported, not assumed.
+ */
+export function fragmentsOf(arg) {
+  const src = String(arg ?? "");
+  const out = [];
+  for (const m of src.matchAll(/["']([^"']+)["']/g)) out.push(m[1]);
+  for (const m of src.matchAll(/`([^`]*)`/g))
+    for (const chunk of m[1].split(/\$\{[^}]*\}/)) if (chunk.trim()) out.push(chunk);
+  return out;
+}
+
+/** A repo-relative module path, or null when the fragments do not spell one (a bare package, `node:`, a
+ *  data URL). Only paths this repository owns can close a cycle inside it. */
+export function resolveSpecifier(fragments, from) {
+  if (!fragments.length) return null;
+  const joined = fragments.join("/").replace(/\/+/g, "/").split("?")[0];
+  if (/^node:/.test(joined)) return null;
+  if (!/\.(mjs|js|cjs)$/.test(joined)) return null;
+  const p = joined.startsWith(".") ? join(dirname(from), joined) : joined.replace(/^\//, "");
+  return normalize(p).split(sep).join("/");
+}
+
+/**
+ * Every specifier that is evaluated when this module is imported.
+ *
+ * TWO FORMS, AND READING ONLY THE FIRST MAKES THIS CHECK BLIND TO THE THING IT IS FOR. `import x from "y"`
+ * and `export { a } from "y"` carry `from`; a SIDE-EFFECT import — `import "y";` — does not, and it
+ * evaluates the module just the same. Four binaries in this tree open with one. Found in review by
+ * planting `import "…/render-units.mjs";` into the leaf that renderer loads from inside its top-level
+ * await: this check reported nothing and exited 0 while the command itself exited 13 on the unsettled
+ * await. Same failure, same pair, silently passed.
+ *
+ * A dynamic `import("y")` is not matched here and must not be: the parenthesis is what distinguishes it,
+ * and it is an edge only where the await reaches it.
+ */
+export function staticSpecifiers(src) {
+  const text = String(src ?? "");
+  const out = [];
+  for (const m of text.matchAll(/(?:^|\n)\s*(?:import|export)\s[^;]*?from\s*["']([^"']+)["']/g)) out.push(m[1]);
+  for (const m of text.matchAll(/(?:^|\n)\s*import\s*["']([^"']+)["']/g)) out.push(m[1]);
+  return [...new Set(out)];
+}
+
+/** The body of a named async function or arrow, by brace matching. */
+export function bodyOf(src, name) {
+  const text = String(src ?? "");
+  const re = new RegExp(`(?:async\\s+function\\s+${name}\\s*\\(|(?:const|let|var)\\s+${name}\\s*=\\s*async\\s*(?:\\([^)]*\\)|[A-Za-z_$][\\w$]*)\\s*=>)`, "m");
+  const m = re.exec(text);
+  if (!m) return null;
+  const open = text.indexOf("{", m.index);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let j = open; j < text.length; j++) {
+    const c = text[j];
+    if (c === "{") depth++;
+    else if (c === "}") { depth--; if (!depth) return text.slice(open, j + 1); }
+  }
+  return null;
+}
+
+const awaitedCalls = (text) =>
+  [...String(text ?? "").matchAll(/await\s+([A-Za-z_$][\w$]*)\s*\(/g)].map((m) => m[1]).filter((n) => n !== "import");
+
+/**
+ * The reader, and the two answers it must keep apart.
+ *
+ * A FILE THAT IS NOT THERE IS A FACT; A FILE THAT WOULD NOT READ IS A COULD-NOT-LOOK. One `catch` returning
+ * nothing collapses them, and then a file too large for the read buffer is filed as absent and quietly left
+ * out of the walk — which is what happened while this check was being built, over a module that exists.
+ */
+export function makeReader(read = readFileSync) {
+  const missing = [];
+  const unreadable = [];
+  const cache = new Map();
+  const readSource = (rel) => {
+    if (cache.has(rel)) return cache.get(rel);
+    let out = null;
+    try {
+      out = read(join(ROOT, rel), "utf8");
+    } catch (e) {
+      if (e?.code === "ENOENT" || e?.code === "ENOTDIR") missing.push(rel);
+      else unreadable.push(`${rel} (${e?.code ?? e?.message ?? "unknown"})`);
+    }
+    cache.set(rel, out);
+    return out;
+  };
+  return { readSource, missing, unreadable };
+}
+
+/** Every `.mjs` under the roots this repository owns. */
+export function moduleFiles(root = ROOT, roots = ROOTS, list = readdirSync, stat = statSync) {
+  const out = [];
+  const walk = (rel) => {
+    let entries;
+    try { entries = list(join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (SKIP.has(e.name)) continue;
+      const child = rel ? `${rel}/${e.name}` : e.name;
+      const isDir = e.isDirectory?.() ?? stat(join(root, child)).isDirectory();
+      if (isDir) walk(child);
+      else if (e.name.endsWith(".mjs")) out.push(child);
+    }
+  };
+  for (const r of roots) walk(r);
+  return out.sort();
+}
+
+/** A module that decides whether it was run rather than imported. */
+export const isEntryPointSource = (src) => /isEntrypoint\(|import\.meta\.url === /.test(String(src ?? ""));
+
+/**
+ * What an entry point reaches WHILE its top-level await is settling.
+ *
+ * Seeds are the calls awaited at the top level and any `import()` written there. From each seed we take the
+ * function of that name in the same file and follow what it awaits, to a fixed point — the call path, not
+ * the whole module.
+ */
+export function reachedDuringTopLevelAwait(entry, src) {
+  const seeds = new Set();
+  const args = [];
+  const lines = String(src ?? "").split("\n");
+  for (const i of topLevelAwaitLines(src)) {
+    for (const c of awaitedCalls(lines[i])) seeds.add(c);
+    for (const a of importArguments(lines[i])) args.push(a);
+  }
+  const walked = new Set();
+  const queue = [...seeds];
+  while (queue.length) {
+    const name = queue.shift();
+    if (walked.has(name)) continue;
+    walked.add(name);
+    const body = bodyOf(src, name);
+    if (!body) continue;
+    for (const a of importArguments(body)) args.push(a);
+    for (const c of awaitedCalls(body)) if (!walked.has(c)) queue.push(c);
+  }
+  const modules = new Set();
+  const unresolved = [];
+  for (const a of args) {
+    const frags = fragmentsOf(a);
+    if (!frags.length) { unresolved.push(a.trim().replace(/\s+/g, " ").slice(0, 70)); continue; }
+    const r = resolveSpecifier(frags, entry);
+    if (r) modules.add(r);
+  }
+  return { modules, unresolved, awaited: [...seeds] };
+}
+
+/** Everything evaluated when `start` is imported: itself, and the static closure beneath it. */
+export function staticClosureOf(start, readSource) {
+  const seen = new Set();
+  const queue = [start];
+  while (queue.length) {
+    const p = queue.shift();
+    if (seen.has(p)) continue;
+    seen.add(p);
+    const src = readSource(p);
+    if (!src) continue;
+    for (const spec of staticSpecifiers(src)) {
+      if (!spec.startsWith(".")) continue;
+      queue.push(normalize(join(dirname(p), spec)).split(sep).join("/"));
+    }
+  }
+  return seen;
+}
+
+/** The whole check, as data. Callers decide what to print and what to exit. */
+export function scan({ read = readFileSync, list = readdirSync } = {}) {
+  const { readSource, missing, unreadable } = makeReader(read);
+  const files = moduleFiles(ROOT, ROOTS, list);
+  const entries = files.filter((f) => isEntryPointSource(readSource(f)));
+  const withTopLevelAwait = [];
+  const violations = [];
+  const unresolved = [];
+  for (const entry of entries) {
+    const src = readSource(entry);
+    if (!src) continue;
+    const reached = reachedDuringTopLevelAwait(entry, src);
+    if (!topLevelAwaitLines(src).length) continue;
+    withTopLevelAwait.push(entry);
+    for (const u of reached.unresolved) unresolved.push(`${entry}: ${u}`);
+    for (const mod of reached.modules) {
+      for (const inClosure of staticClosureOf(mod, readSource)) {
+        const src2 = readSource(inClosure);
+        if (!src2) continue;
+        for (const spec of staticSpecifiers(src2)) {
+          if (!spec.startsWith(".")) continue;
+          const target = normalize(join(dirname(inClosure), spec)).split(sep).join("/");
+          if (target === entry) violations.push({ entry, importer: inClosure, reached: mod });
+        }
+      }
+    }
+  }
+  const undeclaredAbsent = [...new Set(missing)].filter((m) => !KNOWN_ABSENT.includes(m));
+  return { scanned: files.length, entries, withTopLevelAwait, violations, unresolved,
+    missing: [...new Set(missing)], undeclaredAbsent, unreadable: [...new Set(unreadable)] };
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || (process.argv[1] ?? "").endsWith("import-cycle-check.mjs")) {
+  let r;
+  try { r = scan(); }
+  catch (e) {
+    console.error(`import-cycle-check: could not read the tree (${e?.code ?? e?.message}). Nothing was checked.`);
+    process.exit(2);
+  }
+
+  console.log(`import-cycle-check: ${r.scanned} modules, ${r.entries.length} of them commands, `
+    + `${r.withTopLevelAwait.length} of those awaiting at the top level.`);
+
+  // COULD NOT LOOK — never a pass, and three separate ways to get there.
+  if (r.withTopLevelAwait.length < POPULATION_FLOOR) {
+    console.error(`import-cycle-check: only ${r.withTopLevelAwait.length} commands await at the top level, `
+      + `and ${POPULATION_FLOOR} is the floor. The scanner has stopped recognising its subject — read it `
+      + "before trusting this run.");
+    process.exit(2);
+  }
+  if (r.unreadable.length) {
+    console.error("import-cycle-check: these files would not read, so the walk below is incomplete:");
+    for (const u of r.unreadable) console.error(`    ${u}`);
+    process.exit(2);
+  }
+  if (r.undeclaredAbsent.length) {
+    console.error("import-cycle-check: these modules are reached during a top-level await and are not in the "
+      + "tree, and nothing here declares them absent:");
+    for (const m of r.undeclaredAbsent) console.error(`    ${m}`);
+    console.error("\nAdd it to KNOWN_ABSENT with the reason, or fix the path. An absence nobody declared is "
+      + "a module this check silently stopped following.");
+    process.exit(2);
+  }
+  if (r.unresolved.length) {
+    console.error("import-cycle-check: these dynamic imports have a specifier this check could not read, so "
+      + "what they reach is unknown:");
+    for (const u of r.unresolved) console.error(`    ${u}`);
+    process.exit(2);
+  }
+
+  if (!r.violations.length) {
+    console.log("import-cycle-check: nothing any of them awaits imports it back.");
+    process.exit(0);
+  }
+
+  console.error("");
+  console.error("These commands are imported back by something they reach while their top-level await is settling:");
+  for (const v of r.violations) console.error(`    ${v.entry}  <=  ${v.importer}   (reached via ${v.reached})`);
+  console.error("");
+  console.error("Run as a command, each of these hangs: the import asks for a module that is still being");
+  console.error("evaluated, so it never resolves. Node reports an unsettled top-level await naming the await,");
+  console.error("not this import, and the command installs or runs nothing.");
+  console.error("");
+  console.error("The repair is to move what the importer wanted into a module that imports nothing, and to");
+  console.error("re-export it from the command if its other readers should keep one spelling. Making the");
+  console.error("import dynamic inside a function also closes the loop, but it leaves a command in a");
+  console.error("binary's graph for the next reader to tidy back up.");
+  process.exit(1);
+}

package/scripts/release-install-check.mjs

@@ -73,6 +73,30 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";
  * malformed tarball are deliberately absent: those ARE about the bytes, and calling them could-not-look
  * would let a genuinely broken package publish.
  */
+/**
+ * Did npm say anything of its own, or is this only the runner reporting a non-zero exit?
+ *
+ * `execFileSync` composes "Command failed: <the command>" and appends whatever the child wrote. With npm
+ * silenced — `npm run -s` and `npm --silent` export `npm_config_loglevel=silent` to every child — npm
+ * writes nothing at all, and that first line is the whole of it. Every judgement below reads npm's words,
+ * so with none to read there is nothing to judge: not a refusal, not a clearance, an absence.
+ *
+ * The test is deliberately crude and errs towards SPOKE: any content beyond the command echo counts, so a
+ * message this function has never seen is treated as npm talking rather than as silence. The direction
+ * matters — reading silence as a refusal publishes a verdict nobody made, and that is the defect this
+ * exists for; reading speech as silence only costs a re-run. PURE.
+ */
+export function npmSpoke(said) {
+  const text = String(said ?? "").trim();
+  if (!text) return false;
+  const rest = text
+    .split("\n")
+    .filter((l) => l.trim() && !/^Command failed:/i.test(l.trim()))
+    .join("")
+    .trim();
+  return rest.length > 0;
+}
+
 export function looksLikeCouldNotLook(said) {
   return /\b(ENOTCACHED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAGAIN|ENOSPC|ENOENT|ERR_SOCKET_TIMEOUT)\b/i
     .test(String(said ?? ""))
@@ -116,10 +140,28 @@ export function installsAsADependency(tarballPath, { keep = false, timeoutMs = 9
       `${JSON.stringify({ name: "clearotron-install-check-consumer", version: "1.0.0", private: true }, null, 2)}\n`);
 
     try {
-      execFileSync("npm", ["install", abs, "--no-audit", "--no-fund"],
-        { cwd: consumer, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs });
+      // NPM IS TOLD TO SPEAK, RATHER THAN INHERITING WHETHER IT MAY. This check reads npm's own words —
+      // it is the only thing that tells a reader WHY an install failed — and `npm run -s`, which is how a
+      // suite or a release script is often started, exports `npm_config_loglevel=silent` to everything
+      // beneath it. Silenced, npm exits non-zero and prints nothing, and this file then reports a refusal
+      // it could not read as a statement about the artefact. Measured 2026-09-12: the same three tests
+      // red under `npm run -s` and green without it, on the same tree, in three seconds either way.
+      execFileSync("npm", ["install", abs, "--no-audit", "--no-fund", "--loglevel", "error"],
+        { cwd: consumer, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs,
+          env: { ...process.env, npm_config_loglevel: "error" } });
     } catch (e) {
       const said = `${e?.stderr ?? ""}`.trim() || `${e?.stdout ?? ""}`.trim() || `${e?.message ?? e}`;
+      // AN ANSWER NOBODY CAN READ IS NOT A VERDICT ON THE BYTES. When npm says nothing of its own — both
+      // streams empty, so `said` is the runner's "Command failed: npm install …" and nothing else — this
+      // file used to call it a refusal and exit 1, which is a statement that the artefact is broken made
+      // out of an absence. It is a could-not-look: the install did not get far enough to answer.
+      if (!npmSpoke(said)) {
+        return { ok: false, couldNotLook: true, missingBins: [], installed: null,
+          why: "npm exited non-zero and said nothing of its own, so there is no refusal to read:\n\n"
+            + `${said}\n\nThis says nothing about the artefact. Run the check again with npm allowed to `
+            + "speak — `npm run -s` and `npm --silent` pass `npm_config_loglevel=silent` to everything "
+            + "beneath them — and it will either refuse with npm's reason or clear these bytes." };
+      }
       if (looksLikeCouldNotLook(said)) {
         return { ok: false, couldNotLook: true, missingBins: [], installed: null,
           why: `npm could not complete an install here for a reason that is not about these bytes:\n\n${said}` };
@@ -176,6 +218,13 @@ function main() {
     process.exit(2);
   }
 
+  // ── THE ORDER OF THESE TWO BLOCKS IS THE CORRECTNESS, NOT EITHER CONDITION ──────────────────────────
+  //
+  // Every could-not-look return also carries `ok: false`, so both blocks match the same result and the
+  // first one wins. Tested in this order, an absence exits 2 and never reaches the refusal below. Swapped,
+  // it exits 1 — a statement that somebody's package is broken, made out of an answer nobody could read —
+  // and nothing in either block looks wrong on its own. What holds it is the arm that drives this command
+  // and asserts the code, whose message names the consequence rather than the number.
   if (r.couldNotLook) {
     console.error(`  COULD NOT LOOK (exit 2): ${r.why}\n`);
     console.error("  This says nothing about the artefact. It has not been cleared and it has not been "

package/scripts/release-notes-lint.mjs

@@ -26,7 +26,7 @@ import { lineFindings, sourceDirectories, userDocs } from "./plain-language-rule
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
 /** The three groups a note belongs to on the page. User-facing first, as the contract orders them. */
-export const GROUPS = ["New", "Fixed", "For operators"];
+export const GROUPS = ["Before you upgrade", "New", "Fixed", "For operators"];
 
 /** At most this many words in a sentence. The contract's number, not a tuned one. */
 export const MAX_WORDS = 25;
@@ -155,7 +155,7 @@ export function findings(text, {
 
   // The group, which is how the page is ordered. Not part of the owner's contract text — it is the
   // mechanism that delivers its rule 5 — so it is checked first and named as itself.
-  const group = /^(New|Fixed|For operators):\s/.exec(body)?.[1];
+  const group = /^(Before you upgrade|New|Fixed|For operators):\s/.exec(body)?.[1];
   if (!group) {
     out.push({
       line: bodyStart + 1,

package/scripts/release-version.mjs

@@ -30,7 +30,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const GROUP = ["driver", "mcp-server", "portal-ui", "providers/oauth-mcp-bridge"];
 /** The page's order, user-facing first, from the owner's contract. */
-export const GROUPS = ["New", "Fixed", "For operators"];
+export const GROUPS = ["Before you upgrade", "New", "Fixed", "For operators"];
 const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
 
 /** PURE. Where `version` is already out: tagged in this checkout, published on the registry, both, or neither. */
@@ -126,7 +126,7 @@ export function notesOf(section) {
     if (!lines) return;
     const text = lines.join(" ");
     lines = null;
-    const own = /^(New|Fixed|For operators):\s/.exec(text)?.[1];
+    const own = /^(Before you upgrade|New|Fixed|For operators):\s/.exec(text)?.[1];
     if (own) current = own;
     note.push(own || !current ? text : `${current}: ${text}`);
   };
@@ -177,7 +177,7 @@ export function group(bullets) {
   const groups = Object.fromEntries(GROUPS.map((g) => [g, []]));
   const ungrouped = [];
   for (const b of bullets) {
-    const m = /^(New|Fixed|For operators):\s+(.*)$/s.exec(b);
+    const m = /^(Before you upgrade|New|Fixed|For operators):\s+(.*)$/s.exec(b);
     if (!m) { ungrouped.push(b); continue; }
     groups[m[1]].push(m[2].trim());
   }