clearotron 0.2.0 → 0.2.2

package/scripts/strip-tracker-citations.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// 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
+//
+// Removes the internal citation OPENER from comments and prose in the tree (tracker issue 309).
+//
+// The form is `tracker issue NNN — ` standing at the head of a sentence, where the citation is not part
+// of what the sentence says but a label in front of it. Stripping the opener leaves the sentence intact:
+//
+//     // tracker issue 1149 — the walk must start at the repository root
+//     // the walk must start at the repository root
+//
+//     assert.ok(x, "Refs tracker issue 2075 — an absent file is a finding")
+//     assert.ok(x, "an absent file is a finding")
+//
+// WHY THE PATTERN LOOKS OVER-SPECIFIED. Three parts of it are load-bearing and each was measured, not
+// reasoned:
+//
+//   · THE CAPTURE GROUP. The match begins at the line opener — a comment leader, a quote, a bracket —
+//     and the replacement is `$1`, which puts that opener back. Without the group the sweep deletes the
+//     opening quote of every test name it touches, and a broken string literal is a syntax error in the
+//     lucky cases and a changed assertion in the unlucky ones.
+//   · `\s+` AFTER THE SEPARATOR, never `\s*`. `tracker issue 1149-12` is an ITEM suffix, not a citation
+//     followed by prose: there is no space after its hyphen. `\s*` eats the item number.
+//   · THE `i` FLAG. `Refs tracker issue NNN` is capitalised at the head of a commit-style line and is a
+//     fifth of the corpus.
+//
+// WHAT IT WILL NOT TOUCH, and both exclusions are BY NAME rather than by pattern, because a pattern that
+// could recognise them could also stop recognising them:
+//
+//   · THE FILES THAT USE A CITATION AS TEST DATA. Three tests feed a citation to the guard that refuses
+//     citations and assert what comes back. A sweep that rewrites their fixtures edits the corpus the
+//     guard is checked against, and the guard then passes on something it has stopped checking. That is
+//     a green tick bought by deleting the question.
+//   · THE FROZEN RENDERER. `driver/publish/render.mjs` is pinned at a content hash. Changing it reds its
+//     freeze check, and the repair of a sentence is not worth spending a freeze on; touching it needs an
+//     entry in the break ledger, which is a decision and not a sweep.
+//
+// USAGE
+//
+//     node scripts/strip-tracker-citations.mjs            # report only: per-class counts + hand-off list
+//     node scripts/strip-tracker-citations.mjs --apply    # rewrite the mechanical cases
+//
+// The report is the default because the hand-off list is the point: the lines this cannot do are the
+// ones a person has to read, and a sweep that rewrote first would bury them.
+//
+// THIS COUNTS EVERY LINE CARRYING THE FORM, including lines another stripper would also catch. That is
+// deliberate and it is why this number will not match the reference-strip backlog's. A sweep STRIPS; a
+// backlog SELECTS. Overlapping strippers cost nothing and a missed line ships a citation into a public
+// tree, so the population here is the whole corpus rather than the residue left after other rules have
+// taken their share. Reconciling the two numbers is a category error: they answer different questions.
+//
+// A NOTE ON THE OTHER RESIDUE, because the names invite the confusion. `driver/reference-strip-
+// signatures.mjs` counts a DIFFERENT thing — sentences the earlier strip left unfinished, `'s` with
+// nothing to possess and a dangling `pre- `. That is damage: a defect whether or not anyone rules on
+// citations, with a floor that should fall to zero as sentences are repaired. This file's subject is
+// intact text that a ruling removes, whose population goes to zero the day the sweep runs and then
+// wants a guard against reintroduction rather than a backlog. Different residue, different repair.
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const APPLY = process.argv.includes("--apply");
+
+// The mechanical case: a citation standing in front of a sentence, with the opener captured so it
+// survives the replacement.
+export const OPENER = /((?:^|["'`(\[]|\/\/|\/\*|#|\*|·|──)\s*)(?:refs\s+)?tracker issues?\s+\d+\s*[—:–-]\s+/i;
+
+// Any remaining citation, mechanical or not. The difference between this count and the opener count is
+// the hand-off: a citation inside a sentence cannot be removed without rewriting the sentence around it.
+export const ANY_CITATION = /\btracker issues?\s+\d+/i;
+
+export const EXCLUDED = [
+  // Citations used as literal test DATA — the corpus the citation guard is checked against.
+  "driver/test/a-bare-reference-added-in-a-diff-is-refused.test.mjs",
+  "driver/test/prompt-payload-names-no-tracker-issue.test.mjs",
+  "driver/test/euipo-environment-doctrine.test.mjs",
+  // Pinned at a content hash; a prose repair is not worth spending a freeze on.
+  "driver/publish/render.mjs",
+];
+
+export const isScannable = (f) =>
+  /\.(mjs|md|yml|ts|js|json)$/.test(f) && !f.startsWith("portal-ui/dist/") && !EXCLUDED.includes(f);
+
+/** Per-file classification. PURE, and `read` is injected so an arm can drive it over a synthetic tree. */
+export function surveyOf(files, read) {
+  const stripped = {}, handoff = [];
+  let strippedTotal = 0, remainingTotal = 0;
+  for (const f of files.filter(isScannable)) {
+    let text;
+    try { text = read(f); } catch { continue; }
+    let n = 0;
+    const out = text.split("\n").map((line, i) => {
+      if (OPENER.test(line)) { n++; return line.replace(OPENER, "$1"); }
+      if (ANY_CITATION.test(line)) handoff.push({ file: f, line: i + 1, text: line.trim() });
+      return line;
+    });
+    if (n) { stripped[f] = n; strippedTotal += n; }
+    remainingTotal += out.filter((l) => ANY_CITATION.test(l)).length;
+    if (APPLY && n) writeFileSync(join(ROOT, f), out.join("\n"));
+  }
+  return { strippedTotal, remainingTotal, stripped, handoff };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const tracked = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
+    .split("\n").filter(Boolean);
+  const s = surveyOf(tracked, (f) => readFileSync(join(ROOT, f), "utf8"));
+  console.log(`${APPLY ? "stripped" : "would strip"} ${s.strippedTotal} opener(s) across ${Object.keys(s.stripped).length} file(s)`);
+  console.log(`${s.handoff.length} citation(s) are NOT openers and need a reader — the hand-off list:`);
+  for (const h of s.handoff) console.log(`  ${h.file}:${h.line}  ${h.text.slice(0, 110)}`);
+  console.log(`\n${s.remainingTotal} citation(s) would remain after this sweep.`);
+  console.log(`excluded by name: ${EXCLUDED.join(", ")}`);
+}

package/scripts/test-run.mjs

@@ -25,7 +25,7 @@
 //
 // The second obvious fix is a posttest sweeper matching fixture prefixes with an mtime floor. But agents
 // run these suites CONCURRENTLY — that is how the box filled in the first place — so "delete everything
-// matching prelim-mock-* older than N" can delete another run's live fixtures. Prefix matching cannot
+// matching clearotron-mock-* older than N" can delete another run's live fixtures. Prefix matching cannot
 // distinguish my fixtures from yours.
 //
 // A third option needs neither. os.tmpdir() honours TMPDIR, and every leaking call site is already
@@ -65,7 +65,7 @@ import { snapshotRepo, repoWrites, explainRepoWrites } from "./repo-writes.mjs";
 //     CLEAROTRON_DATABASE=clarivate node scripts/test-run.mjs node -e '<print>'
 //       -> CLEAROTRON_DATABASE = "corsearch"
 //
-// The operator named a vendor and the suite ran as a different one, in silence. That is 's own
+// The operator named a vendor and the suite ran as a different one, in silence. That is its own
 // sentence — "a default is the one wrong value that never announces itself" — reached through the
 // compatibility window rather than through a code default.
 //
@@ -286,7 +286,7 @@ if (missingDeps.length) {
   process.exit(1);
 }
 
-// ── THE SUITE CANNOT READ THE OPERATOR'S CONFIGURATION, IN OR OUT (,) ──────────────────
+// ── THE SUITE CANNOT READ THE OPERATOR'S CONFIGURATION, IN OR OUT () ──────────────────
 //
 // TWO DIRECTIONS, ONE SEAT. The guard below refuses when a data-plane ROOT escapes; these two stop the
 // suite reading the operator's configuration and stop it writing into their data plane. Same wrapper,

package/scripts/third-party-notices.mjs

@@ -171,7 +171,7 @@ function resolveInstalled(root, name, path) {
 }
 
 /**
- * tracker issue 146 — WHY `npm ls` IS COMPLAINING, WHEN THE ANSWER IS NOT IN THE CODE AT ALL.
+ * WHY `npm ls` IS COMPLAINING, WHEN THE ANSWER IS NOT IN THE CODE AT ALL.
  *
  * Adding a `git worktree` and symlinking `node_modules` from another one — the obvious way to skip a
  * five-minute install — makes six licence arms fail in a way that reads exactly like a code defect, on
@@ -257,7 +257,7 @@ export function collect(root = ROOT, tree = npmTree(root), { linkTarget = defaul
       + "this file has not been looked at:\n  " + undeclared.slice(0, 12).join("\n  ")
       + (undeclared.length > 12 ? `\n  …and ${undeclared.length - 12} more` : "")
       + "\n\nFix the tree, or declare it in DECLARED_LS_PROBLEMS with the reason it is allowed."
-      // tracker issue 146 — appended, never substituted: a real problem keeps the sentence above.
+      // appended, never substituted: a real problem keeps the sentence above.
       + (foreignTreeNote(root, undeclared, { linkTarget }) ?? ""));
   }
   // ── ONE PACKAGE, SEVERAL NODES, AND ONLY ONE OF THEM CARRIES THE CHILDREN ──────────────────────
@@ -382,7 +382,7 @@ if (isEntrypoint(import.meta.url)) {
   if (!check) { writeFileSync(OUTPUT, next); console.log(`third-party-notices: wrote ${OUTPUT}`); process.exit(0); }
   const now = existsSync(OUTPUT) ? readFileSync(OUTPUT, "utf8") : null;
   if (now === next) { console.log("third-party-notices: THIRD-PARTY-NOTICES.md matches the installed production tree."); process.exit(0); }
-  // ── Refs tracker issue 2073 — THE REFUSAL SAYS HOW TO FIX IT, INCLUDING THE HALF THAT IS FORGOTTEN ──
+  // ── THE REFUSAL SAYS HOW TO FIX IT, INCLUDING THE HALF THAT IS FORGOTTEN ──
   //
   // "regenerate with: <script>" was true and insufficient. What reds CI is a PRODUCTION-DEPENDENCY BUMP
   // whose regenerated notices file was not COMMITTED WITH IT, and the committing half is the half that

package/scripts/travelling-predicates.mjs

@@ -1,7 +1,7 @@
 // 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
 //
-// travelling-predicates.mjs — 's candidate population, DISCOVERED rather than recalled.
+// travelling-predicates.mjs — the candidate population, DISCOVERED rather than recalled.
 //
 // hunts a class: a contract whose two ends measure different things — a demand computed against
 // one unit or snapshot, satisfaction enforced against another, with no guard asserting the two agree.
@@ -42,7 +42,7 @@
 //   looked like an assignment, and filed `const push = (row) => { if (!asks.some(…)) … }` as "stored"
 //   because the line starts with `const`. That is a proxy validating a proxy. This parses.
 //
-// ── THE SECOND QUESTION: WHERE DOES IT COME TO REST? ('s adjudication set) ──────────────────────
+// ── THE SECOND QUESTION: WHERE DOES IT COME TO REST? (the adjudication set) ──────────────────────
 //
 // "Travelling" is a candidate ceiling and this file has said so since it was written. Ninety-nine
 // candidates is not a population anybody adjudicates one essay at a time, and reading them as ninety-nine
@@ -59,7 +59,7 @@
 //
 //   structure   written into something that OUTLIVES the expression that computed it — an object field,
 //               an assignment, or a local that lands in a returned object. THIS is the class's shape:
-//               's `quote_required` was a flag on a form, judged later against candidates that had
+//               That `quote_required` was a flag on a form, judged later against candidates that had
 //               been rebuilt. A boolean at rest can be met by data that has moved.
 //
 // The three are exhaustive and mechanical, so the sweep's own numbers say how much reading is owed and

package/scripts/unexecuted-asserts.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // 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
-// unexecuted-asserts.mjs — 's fifth member: an arm that RAN and asserted nothing.
+// unexecuted-asserts.mjs — the fifth member: an arm that RAN and asserted nothing.
 //
 //   node scripts/unexecuted-asserts.mjs <lcov>            # DRY RUN — prints what would change
 //   node scripts/unexecuted-asserts.mjs <lcov> --apply    # writes it
@@ -199,7 +199,7 @@ if (isEntrypoint(import.meta.url)) {
     // THE REMEDY IS THE WHOLE COMMAND, not a placeholder. Whoever this fires on has probably never heard
     // of CT_COVERAGE_DIR — it is set in ci.yml and nowhere a contributor reads — so `<lcov>` sends them to
     // the workflow file to find out what to substitute. A guard whose remedy has to be looked up is a
-    // guard people delete ('s own rule, applied to its own error message).
+    // guard people delete (its own rule, applied to its own error message).
     console.error(`\nCHECK FAILED — ${grew.length} file(s) grew an assert site that never ran.\n\n`
       + "READ EACH ONE FIRST. An arm that stopped asserting is the defect this exists to find (#1010);\n"
       + "a new honest branch — a platform check, an else nobody takes here — is re-stamped deliberately:\n\n"

package/scripts/verify-publishable.mjs

@@ -49,7 +49,7 @@ const staging = mkdtempSync(join(tmpdir(), "clearotron-verify-"));
 // ── CAN THIS RUN ON THE TREE IT IS POINTED AT — tracker issue 196 ───────────────────────────────────
 //
 // THIS SCRIPT WAS INVOKED BY NOTHING for as long as it has existed on the public tree: no workflow, no
-// npm script, every other mention of its name a comment. That is tracker issue 189's shape — an
+// npm script, every other mention of its name a comment. That is the shape — an
 // instrument that exists, has stopped being reachable, and whose silence is indistinguishable from a
 // pass. Five uninstallable releases shipped past it.
 //
@@ -82,7 +82,7 @@ if (!existsSync(CUT_TABLE)) {
   console.error("  dependency, in CI and again at publish. That covers the manifest. It does not type the verbs");
   console.error("  and it does not check the substitution.\n");
   console.error("  To make this runnable, the pack's reconcile step needs either the cut table or a decision that");
-  console.error("  it does not need it. That decision is tracker issue 196's stated out-of-scope and is nobody's yet.");
+  console.error("  it does not need it. That decision is stated out of scope and is nobody's yet.");
   process.exit(2);
 }
 

package/scripts/write-up-form-census.mjs

@@ -34,7 +34,7 @@
 //   1. UNRESOLVED DEPTH. `depthFor` falls back to full-country depth stamped `default-ungraded` when it
 //      cannot resolve a policy, and `writeUpForm` maps every ungraded rung to `full`. A census built on a
 //      policy object that does not resolve therefore reports "every product authors every card, the ladder
-//      saves nothing" — quotable, and false. 's own ladder shipped dead for exactly this reason. So
+//      saves nothing" — quotable, and false. its own ladder shipped dead for exactly this reason. So
 //      the depth row is asserted resolved before a single finding is counted.
 //   2. NO BAND SHAPE. The floor tier joins from `band-shape.json`; absent, every finding reads as holding
 //      no floor and the graded products UNDER-count their full cards — erasing the one class the owner

package/shared/access-audience.mjs

@@ -71,3 +71,218 @@ export function audienceLabel(aud) {
   if (!list.length) return "(none)";
   return list.map((a) => `${String(a).slice(0, 8)}…`).join(",");
 }
+
+// ── THE AUDIENCE THE EDGE ISSUES, AS OPPOSED TO THE ONE THIS INSTALL EXPECTS (tracker issue 241) ───
+//
+// Everything above reads LOCAL configuration. What follows reads the EDGE, so `doctor` can compare the
+// two — the half of the recreation trap with no symptom of its own. Deleting and recreating a
+// Cloudflare Access application changes the audience; the existing warning fires on the CHALLENGE being
+// wrong, so on a box where somebody recreated the application and then fixed the sign-in, every layer
+// reads healthy and the stale audience stays invisible until a real request is rejected.
+//
+// ── WHERE THE AUDIENCE IS, AND WHERE IT IS NOT ───────────────────────────────────────────────────
+//
+// Access does not publish it in RFC 8414 discovery metadata. Two investigations looked there, correctly
+// found nothing, and one concluded the route did not exist. It is in the REDIRECT handed to an
+// unauthenticated caller: the login URL carries a `kid` parameter and a `meta` JWT naming the same value.
+//
+// ── THIS DECODES; IT DOES NOT VERIFY, AND THAT IS DELIBERATE ─────────────────────────────────────
+//
+// The meta token is public routing information served to a caller with no credential — its own
+// `auth_status` reads `NONE`. It is not a bearer token and nothing here trusts it: the only thing taken
+// from it is a string, which is then compared against local configuration. Verifying it would mean
+// dragging in the credential path and `jose` with it — which this file's header explains at length that
+// it must not do — to authenticate a document that authenticates nobody, and would invite a later
+// reader to believe a valid signature here meant a request was authorised. It does not.
+//
+// ── AND THE READ IS CROSS-CHECKED AGAINST ITSELF ─────────────────────────────────────────────────
+//
+// The same value arrives two independent ways in one response: the `kid` parameter and the token's own
+// `aud`. Using one when two are there throws away the only free integrity check on the read, and it is
+// the check that would catch this code keying on a field Cloudflare later moves. When they disagree
+// this reports the disagreement rather than picking a winner.
+/** The path that says a hostname is Access-fronted. */
+export const ACCESS_LOGIN_PATH = "/cdn-cgi/access/login/";
+
+/** Base64url → utf8, with no exception escaping to the caller as a silent empty string. */
+function decodeSegment(seg) {
+  const raw = Buffer.from(String(seg), "base64url").toString("utf8");
+  if (!raw) throw new Error("the segment decoded to nothing");
+  return raw;
+}
+
+/**
+ * The audience, read out of the location an unauthenticated request was redirected to.
+ *
+ * `kind` is the whole answer and every branch has one, because the failures here are NOT
+ * interchangeable and the caller must be able to tell them apart:
+ *
+ *   unreachable      the edge could not be asked. A could-not-look, never agreement.
+ *   not-fronted      the hostname answered without an Access challenge. Its own verdict, and the
+ *                    single most important one: this check must not be able to SUCCEED by failing to
+ *                    find an edge, which is the exact shape of the defect it exists to catch.
+ *   unreadable       there is a challenge, and the audience could not be read out of it. Also a
+ *                    could-not-look — the shape may have moved, and a moved shape is not agreement.
+ *   disagree         `kid` and the token's `aud` name different audiences.
+ *   read             one audience, agreed by both sources.
+ */
+// The marker an Access-fronted API path puts in `WWW-Authenticate`. Keyed on the RESOURCE-METADATA path
+// rather than on "Bearer", which any OAuth resource anywhere would send — this names Cloudflare Access
+// specifically, and it is the string the real door returns.
+const ACCESS_RESOURCE_RE = /cloudflare-access-protected-resource/i;
+
+export function readAudience({ location = "", status = null, error = null, wwwAuthenticate = "", viaEdge = false } = {}) {
+  if (error) return { kind: "unreachable", why: String(error?.message ?? error).slice(0, 200) };
+  // ── THREE DOORS, NOT ONE (tracker issue 251) ────────────────────────────────────────────────────
+  //
+  // This returned `not-fronted` for every response with no redirect, and measured against production's
+  // four configured hostnames that one label covered three materially different states:
+  //
+  //   trademark.cordillera.ch        302  redirect present  → audience read, kid agrees
+  //   mcp.cordillera.ch/mcp          401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   clients-mcp.cordillera.ch/mcp  401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   agent-mcp.cordillera.ch/mcp    502  no redirect       → not-fronted   ← an origin fault
+  //
+  // None of these was a false pass — every one returned ok:false, which is the property that matters
+  // most and is untouched. It was a WRONG DIAGNOSIS on a safe failure, and the cost is a reader's hour
+  // spent hunting an Access application that exists and is working.
+  if (!location) {
+    // FRONTED, API PATH. Managed OAuth on an MCP path answers RFC 9728 style instead of redirecting a
+    // browser: a 401 whose `WWW-Authenticate` names a Cloudflare Access protected-resource document.
+    // Measured on the real door — that document resolves 200, says `protected: true`, and carries NO
+    // audience. So this is a stated could-not-look about the audience ON A DOOR THAT IS CONFIRMED
+    // PRESENT, which is neither a pass nor "no door".
+    if (ACCESS_RESOURCE_RE.test(String(wwwAuthenticate ?? ""))) {
+      return { kind: "fronted-api",
+        why: `the hostname answered ${status ?? "401"} as an OAuth-protected resource, naming a Cloudflare `
+          + "Access protected-resource document — it is fronted, and this route carries no audience to read" };
+    }
+    // THE EDGE ANSWERED AND THE ORIGIN DID NOT. A 5xx carrying `cf-ray` is Cloudflare reporting that it
+    // reached the door and the thing behind it did not answer. Calling that "nothing is fronting this
+    // hostname" is exactly backwards.
+    if (viaEdge && Number(status) >= 500) {
+      return { kind: "origin-failed",
+        why: `the edge answered ${status} for this hostname — Cloudflare reached the door and the origin `
+          + "behind it did not answer, so the audience could not be asked for" };
+    }
+    return { kind: "not-fronted", why: `the hostname answered ${status ?? "with no redirect"} and sent no Access challenge` };
+  }
+  let url;
+  try { url = new URL(location); } catch {
+    return { kind: "unreadable", why: `the redirect target is not a URL: ${String(location).slice(0, 120)}` };
+  }
+  if (!url.pathname.includes(ACCESS_LOGIN_PATH)) {
+    return { kind: "not-fronted", why: `the redirect goes to ${url.origin}${url.pathname}, which is not an Access login` };
+  }
+  const kid = url.searchParams.get("kid") || "";
+  const token = url.searchParams.get("meta") || "";
+  if (!token) return { kind: "unreadable", why: "the Access login carries no `meta` token", kid };
+  const parts = token.split(".");
+  if (parts.length < 2) return { kind: "unreadable", why: "the `meta` token is not a JWT", kid };
+  let payload;
+  try { payload = JSON.parse(decodeSegment(parts[1])); } catch (e) {
+    return { kind: "unreadable", why: `the \`meta\` token's payload could not be read (${String(e?.message ?? e).slice(0, 80)})`, kid };
+  }
+  const aud = typeof payload?.aud === "string" ? payload.aud : "";
+  if (!aud) return { kind: "unreadable", why: "the `meta` token's payload names no `aud`", kid };
+  // BOTH SOURCES, OR NEITHER IS TRUSTED. A `kid` that is absent is itself a change in the shape.
+  if (!kid) return { kind: "unreadable", why: "the Access login carries no `kid` to cross-check the token against", aud };
+  if (kid !== aud) {
+    return { kind: "disagree", aud, kid, hostname: payload?.hostname ?? "", why: "the two sources name different audiences" };
+  }
+  return { kind: "read", aud, kid, hostname: payload?.hostname ?? "" };
+}
+
+/**
+ * What to tell the reader, given what was configured and what the edge said.
+ *
+ * NOTHING HERE RETURNS "fine" FOR A QUESTION IT COULD NOT ASK. Each unhappy kind carries its own
+ * sentence naming what was not established, because "no problem reported" and "no problem" are the two
+ * things this whole check exists to keep apart.
+ */
+export function audienceVerdict({ configured = "", read = {} } = {}) {
+  // MEMBERSHIP, NOT EQUALITY, and this file already learned that once. A deployment runs one Access
+  // application PER AUDIENCE and `CLEAROTRON_OIDC_AUDIENCE` may name several; the edge issues ONE for
+  // the hostname being asked. `===` against a configured list reports every correct multi-application
+  // deployment as a mismatch — the same mistake `audienceIncludes` above exists to have stopped making.
+  const cfg = accessAudience(configured);
+  const cfgList = Array.isArray(cfg) ? cfg : (cfg ? [cfg] : []);
+  switch (read.kind) {
+    case "unreachable":
+      return { kind: "could-not-look", ok: false,
+        message: `the edge could not be reached, so the audience it issues is unknown (${read.why}). `
+          + "This is a failure to look, not agreement." };
+    case "not-fronted":
+      return { kind: "not-fronted", ok: false,
+        message: `nothing is fronting this hostname with Access — ${read.why}. A door that is not there `
+          + "cannot be the one this install is configured for, so this is a finding rather than a pass." };
+    // NEITHER A PASS NOR "NO DOOR". The door is confirmed present and the audience is not readable by
+    // this route — that is a stated could-not-look, and it must not read as either of the two things it
+    // is not. Whether an API path's audience is reachable at all is open; nothing in the
+    // protected-resource document carries it.
+    case "fronted-api":
+      return { kind: "fronted-api", ok: false,
+        message: `this hostname IS fronted by Access — ${read.why}. The audience could not be compared, `
+          + "which is a could-not-look about the audience and not a finding about the door." };
+    case "origin-failed":
+      return { kind: "could-not-look", ok: false,
+        message: `the edge is up and the origin behind it is not — ${read.why}. Nothing here says anything `
+          + "about the audience; it says the service is down." };
+    case "unreadable":
+      return { kind: "could-not-look", ok: false,
+        message: `the Access challenge is there but its audience could not be read (${read.why}). `
+          + "The shape may have moved; a shape that moved is not agreement." };
+    case "disagree":
+      return { kind: "sources-disagree", ok: false,
+        message: `the edge's own two answers disagree: the login's \`kid\` says ${read.kid} and the `
+          + `\`meta\` token says ${read.aud}. Neither is trustworthy on its own, so nothing is compared.` };
+    case "read": {
+      if (!cfgList.length) {
+        return { kind: "not-configured", ok: false,
+          message: `the edge issues ${read.aud} for this hostname, and CLEAROTRON_OIDC_AUDIENCE is unset, `
+            + "so every request it fronts is checked against nothing." };
+      }
+      if (!audienceIncludes(cfg, read.aud)) {
+        // BOTH VALUES, NEVER "audience mismatch". A reader who is told only that two things differ has
+        // to go and find both of them, and the whole point of asking the edge was to hand them over.
+        return { kind: "mismatch", ok: false,
+          message: `the audience does not match. This install is configured with ${cfgList.join(", ")}, and the edge `
+            + `issues ${read.aud} for ${read.hostname || "this hostname"}. Requests will be rejected `
+            + "until they agree — recreating an Access application changes the audience." };
+      }
+      return { kind: "agree", ok: true,
+        message: `the audience matches the one the edge issues for ${read.hostname || "this hostname"} (${read.aud})` };
+    }
+    default:
+      return { kind: "could-not-look", ok: false,
+        message: `the audience check returned no verdict it knows (${JSON.stringify(read.kind)}), which is `
+          + "a fault in this check rather than a finding about the door." };
+  }
+}
+
+/**
+ * One unauthenticated request, with a bound on how long it may take.
+ *
+ * `redirect: "manual"` because the REDIRECT is the answer — following it fetches Cloudflare's login page
+ * and throws away the only thing being read. Failure is returned rather than thrown: the caller's job is
+ * to say "could not look", and an exception here would reach `doctor` as a crash instead.
+ */
+export async function probeAudience({ url, fetchImpl = fetch, timeoutMs = 5000, signalFor = null } = {}) {
+  if (!url) return { error: new Error("no hostname is configured to ask") };
+  const ac = signalFor ? null : new AbortController();
+  const t = ac ? setTimeout(() => ac.abort(new Error(`no answer within ${timeoutMs}ms`)), timeoutMs) : null;
+  try {
+    const res = await fetchImpl(url, { redirect: "manual", signal: signalFor ?? ac.signal });
+    // TWO MORE HEADERS, AND THEY ARE THE WHOLE OF THIS CHECK. Without them every non-redirecting
+    // answer collapses to "no redirect", and three different doors read as one. `www-authenticate` is
+    // how an Access-fronted API path announces itself; `cf-ray` is how a 5xx says the EDGE answered and
+    // the origin behind it did not. Both are on the response already — nothing extra is fetched.
+    return { status: res.status, location: res.headers?.get?.("location") ?? "",
+      wwwAuthenticate: res.headers?.get?.("www-authenticate") ?? "",
+      viaEdge: Boolean(res.headers?.get?.("cf-ray")) };
+  } catch (e) {
+    return { error: e };
+  } finally {
+    if (t) clearTimeout(t);
+  }
+}

package/shared/brand.mjs

@@ -26,7 +26,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 // index header, nav brand, Excel metadata, connector instructions). Env-overridable per deployment —
 // branding is tenant config, not code. Read once at import (deployment-static, like the systemd env).
 //
-// CASING: THE VALUE IS PROSE, SO IT IS CAPITALISED (, superseding ruling 2026-08-20). The rule is
+// CASING: THE VALUE IS PROSE, SO IT IS CAPITALISED (superseding ruling 2026-08-20). The rule is
 // Clearotron in prose and UI, `clearotron` in config values, commands, binary names and identifiers.
 // This DEFAULT is prose in every place it lands — report and portal <title>, the pool index header,
 // Excel `creator`, the connector steps, "You reached X" — so it takes the capital. The VARIABLE that
@@ -95,7 +95,7 @@ export const BRAND = {
  *
  * ABSENT IS NOT FALSE. The plain confidentiality line claims nothing and is what any legal deliverable
  * carries; collapsing absent into false is precisely the coercion that shipped House-default clearances
- * with no marking at all. That is 's property and it is untouched.
+ * with no marking at all. That is the property and it is untouched.
  *
  * `true` USED TO SELECT A LONGER LINE — the plain marking plus a legal characterisation of the document
  * — and the owner dropped that wording on 2026-08-20. It renders as the default here rather than being
@@ -154,7 +154,7 @@ export const PALETTE = {
 
 // — THE DARK COUNTERPART. Until this landed, every dark value in the product was a literal typed
 // into whichever block needed it, and the two server-rendered door pages (sign-in, refusal) had guessed
-// their own set — a THIRD ground, tracker issue 17150f, against the brand pack's #0f0e0c.
+// their own set — a THIRD ground, #17150f, against the brand pack's #0f0e0c.
 //
 // The two entries the brand pack fixes are marked; the rest have no pack entry and are the values the
 // warm surfaces already shipped, kept as-is. `cream` has no dark twin by name because a dark ground is
@@ -164,7 +164,7 @@ export const PALETTE_DARK = {
   ground:     '#0f0e0c',              // brand pack §01 "Dark BG" — near-black. Supersedes the doors' #17150f
   ink:        '#f0e8d8',              // brand pack §01 "Parchment" — dark text / mark. Supersedes #ece5d8
   // The three locked crimsons, lifted for the dark ground. `crimson` itself is NOT here: it is a FILL
-  // (badges, the accent) and keeps tracker issue 860F09 in both schemes. Crimson as TEXT is what needs lifting, and
+  // (badges, the accent) and keeps #860F09 in both schemes. Crimson as TEXT is what needs lifting, and
   // that is `crimsonText` — the value the warm and report dark blocks already applied to links.
   crimsonDeep: '#6a0a13',
   crimsonMid:  '#c47f7a',
@@ -350,7 +350,7 @@ export const REPORT_ROOT =
 
   // Risk ramp — the designer's ramp from the portal redesign. It is a BAND family
   // of its own: --high is deliberately NOT --accent any more (the shipped --high was byte-identical to
-  // tracker issue 860F09, so a High risk dot read as a Start button and needed a ring workaround). --accent /
+  // #860F09, so a High risk dot read as a Start button and needed a ring workaround). --accent /
   // --crimson / --maroon above are untouched. The gauge's stop order is clear→low→med→high→severe.
   `--clear:#5F8A64; --low:#8A9440; --med:#C8871B; --high:#B23A2E; --severe:#7C1E15;` +
   // Soft/text pairs: re-derived from the five bases by the rule in shared/tools/derive-band-pairs.mjs (same
@@ -374,12 +374,12 @@ export const REPORT_ROOT =
 //   • *_EXPLICIT variants                         — the `[data-theme="dark"]` block ONLY, no `@media` —
 //     CUSTOMER-facing surfaces (the per-customer index): first view is ALWAYS light; dark only by
 //     the visitor's explicit toggle. The @media string must never appear in client output (tests pin this).
-// Crimson discipline: `--crimson`/`--h-red` KEEP tracker issue 860F09 in dark — they are FILLS (badges, the accent)
-// where white-on-crimson stays high-contrast. `--high` used to be in that list because it WAS tracker issue 860F09;
+// Crimson discipline: `--crimson`/`--h-red` KEEP #860F09 in dark — they are FILLS (badges, the accent)
+// where white-on-crimson stays high-contrast. `--high` used to be in that list because it WAS #860F09;
 // since the 2026-07-19 ramp recolor it is a band token (#B23A2E) and lightens with the rest of the band
 // family. Crimson TEXT uses (links, summaries, the wordmark)
 // are recolored to a lightened #e0736b by SCOPED rules inside the dark block only — zero light-side edits.
-// Every dark hex avoids the BLUE_SKIN regex /#3b4fd6|tracker issue 11132a|#f5f6f9|#1a1a2e/i (note #1b1714 ≠ #1a1a2e).
+// Every dark hex avoids the BLUE_SKIN regex /#3b4fd6|#11132a|#f5f6f9|#1a1a2e/i (note #1b1714 ≠ #1a1a2e).
 //
 // Inside the @media branch, override RULES are prefixed `html:not([data-theme="light"])` (not `:root:not`)
 // on purpose: `:root` would add a full class-level of specificity and out-rank sibling base rules like
@@ -427,7 +427,7 @@ const WARM_DARK_RULES = [
 ];
 
 // Report dark tokens (token-for-token against REPORT_ROOT; --font/--mono unchanged). --crimson keeps
-// tracker issue 860F09 (it is the accent FILL). The risk BANDS are their own family since the 2026-07-19 recolor and
+// #860F09 (it is the accent FILL). The risk BANDS are their own family since the 2026-07-19 recolor and
 // are free to lighten: each is its light base at +11 lightness (severe +10), saturation ×.92 — the same
 // relationship the previous dark ramp used. That relationship is what makes the last stop visible on the
 // dark ramp, and it does so better than before: dark --severe reads 2.70:1 on the page (was 1.74) and
@@ -478,10 +478,10 @@ export const REPORT_ROOT_DARK_EXPLICIT = darkBlock(REPORT_DARK_TOKENS, REPORT_DA
 //
 // WHY IT IS A FAMILY AND NOT A PAGE'S BUSINESS. Both doors are server-rendered by driver/portal-service
 // and each carried its own copy of this block — including a hand-picked dark set that had drifted from
-// the pack (tracker issue 17150f ground, #ece5d8 text) and error colours with no home at all. Two copies of a palette
+// the pack (#17150f ground, #ece5d8 text) and error colours with no home at all. Two copies of a palette
 // is how the light palettes drifted before PALETTE existed.
 //
-// THE GATING IS `[data-theme]` ONLY (, correcting what shipped). The portal's doctrine is
+// THE GATING IS `[data-theme]` ONLY (correcting what shipped). The portal's doctrine is
 // that a CLIENT surface never follows the OS colour preference: first view is always light, and dark
 // arrives only from a choice the visitor made themselves. kept the media query on the argument
 // that these pages have no toggle, so removing it would leave a first-time visitor no route to dark —
@@ -574,7 +574,7 @@ header.rep .theme-toggle{float:right;margin-left:12px}
 // emitted page — including reports published by deployments with no connection to that firm (
 // measured it on the demo pool index, twice on one page). Stripping the label was the fix then;
 // removing the watermark removes the surface.
-// THE SWISS FLAG IS GONE, and it is 's ruling rather than a new one. The portal's lockup
+// THE SWISS FLAG IS GONE, and it is the ruling rather than a new one. The portal's lockup
 // dropped it when the product was renamed — portal-ui/src/components/Logo.tsx states the reason and
 // portal-ui/test/lockup.test.ts pins its ABSENCE so a well-meaning restore fails there:
 //
@@ -639,7 +639,7 @@ export const CHROME_CSS = `
 .lockup .lk-tag{margin-top:5px;font-size:7.5px;font-weight:500;letter-spacing:.22em;text-transform:uppercase;color:var(--muted)}
 .has-glow{position:relative;isolation:isolate}
 .has-glow::before{content:"";position:absolute;top:0;left:0;width:min(92vw,1100px);aspect-ratio:1.5;background:radial-gradient(farthest-side at 0% 0%,var(--web-glow),transparent 72%);pointer-events:none;z-index:-1}
-/* tracker issue 1431 — the .watermark rule and its ::after are GONE. They masked the parent company's ridge behind
+/* the .watermark rule and its ::after are GONE. They masked the parent company's ridge behind
    every report and the pool index; the owner's call is removal, not a bracket version of the same
    thing. The three body elements that carried the class drop it too, and --wm-alpha goes with them:
    a token nothing reads is a knob somebody re-wires.

package/shared/citation-scan.mjs

@@ -47,7 +47,7 @@ export function scanCitations(files, readFn, { paths, excluded, declaredFor, sou
         // Measured at the bound written here: 6 hits, all real. Widen it further only with the same
         // measurement in hand.
         const base = path.endsWith("/") ? null : path.slice(path.lastIndexOf("/") + 1);
-        // AND A DIRECTORY IS CITED BY ITS OWN NAME TOO (, measured 2026-08-24). Three shipping
+        // AND A DIRECTORY IS CITED BY ITS OWN NAME TOO (measured 2026-08-24). Three shipping
         // files named `fixtures/owner-screen-2026-07-29` — a path relative to the file, not to the repo
         // root — so `includes(path)` walked straight past every one of them and the reader got a
         // directory that is not there. The FILES-ONLY bound above was measured against basenames like