clearotron 0.2.2 → 0.2.4

package/scripts/test-full.mjs

@@ -0,0 +1,226 @@
+#!/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
+//
+// RUN EVERY CORPUS, AND REFUSE TO BE SILENT ABOUT ONE THAT WAS NOT RUN.
+//
+//   node scripts/test-full.mjs                 # every corpus
+//   node scripts/test-full.mjs --only providers # one of them
+//   node scripts/test-full.mjs --list           # the plan, run nothing
+//
+// ── WHAT THIS REPLACES, AND WHY A FLAG WAS NOT ENOUGH ────────────────────────────────────────────
+//
+// `npm run test:full --workspaces --if-present` reported this suite green while running part of it.
+// Two separate holes, and only the smaller one is about the flag:
+//
+//   - `providers/` holds twelve directories of register-adapter tests. ELEVEN OF THEM ARE NOT
+//     WORKSPACES — they have no package.json at all — so no `--workspaces` command can reach them,
+//     with or without `--if-present`. That is the larger half and no flag fixes it.
+//   - `--if-present` turns "this workspace declares no such script" into a silent skip. An absence
+//     reading as a pass is the shape this repository refuses everywhere else.
+//
+// So the population is declared here rather than inferred from a flag, and every member of it is
+// either run or named. A corpus that was not run is a line on stdout, never an omission.
+//
+// ── THE RULE, AND THE ONE THING THAT MAY SOFTEN IT ───────────────────────────────────────────────
+//
+// A declared workspace that does not define `test:full` FAILS this command. That is the permissive
+// half of the old gate written the other way round.
+//
+// One softening, because refusing here would be a false refusal: a workspace whose tests are already
+// run by another corpus is COVERED, not missing. `providers/oauth-mcp-bridge` is a workspace with no
+// scripts block whose ten tests run every time the providers corpus does. Failing it would refuse a
+// workspace whose tests demonstrably execute, and giving it a script of its own would split one
+// corpus across two mechanisms and run those files twice.
+//
+// THE EXEMPTION IS CHECKED, NEVER TRUSTED. For each entry below, this command asserts that the
+// covering corpus's own file list actually reaches that workspace, and that the workspace has test
+// files at all. Both halves matter: an intersection with an empty set is empty, so a workspace that
+// lost its tests would satisfy a reachability check that only asked "is nothing missing". If someone
+// narrows the providers file list until it no longer reaches this workspace, the exemption stops
+// being true and this command says so instead of going quiet.
+import { spawnSync } from "node:child_process";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Every `*.test.mjs` under `providers/`, at any depth, deduplicated and ordered.
+ *
+ * RECURSIVE, AND THAT IS THE POINT. This read `providers/<dir>/test/*.test.mjs` and nothing else, one
+ * level deep — and the exemption check below counted a covered workspace's own files with the SAME
+ * shape. So a test at `providers/x/y.test.mjs`, or at `providers/x/test/sub/y.test.mjs`, was in no
+ * corpus at all, both sides missed it together and therefore agreed, and every check reported clean
+ * under a command whose whole claim is that it runs every corpus. Two derived sides sharing one
+ * assumption cannot disagree about it; that is this file's own argument, and it applied here.
+ *
+ * `node_modules` is excluded because an installed dependency's tests are not this repository's corpus.
+ * Nothing else is: a file is either collected or it is a fault, never quietly outside the shape.
+ */
+export function providerTestFiles(root = ROOT) {
+  const base = join(root, "providers");
+  if (!existsSync(base)) return [];
+  const out = new Set();
+  const walk = (dir, rel) => {
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+      if (d.name === "node_modules") continue;
+      const here = `${rel}/${d.name}`;
+      if (d.isDirectory()) walk(join(dir, d.name), here);
+      else if (d.name.endsWith(".test.mjs")) out.add(here);
+    }
+  };
+  walk(base, "providers");
+  // DEDUPLICATED ON PURPOSE. The shell form this replaced listed `providers/_shared/test/*.test.mjs`
+  // and then `providers/*/test/*.test.mjs`, which matches `_shared` as well — 51 paths for 37 files.
+  // Measured before it was called a defect: `node --test` runs a repeated path once, so the old form
+  // executed nothing twice. Building the list here makes that a property rather than a coincidence.
+  return [...out].sort();
+}
+
+/**
+ * A workspace with no `test:full`, whose tests another corpus already runs.
+ * `reaches` is the claim this command verifies on every run — not documentation.
+ */
+export const COVERED_ELSEWHERE = [
+  {
+    workspace: "providers/oauth-mcp-bridge",
+    corpus: "providers",
+    why: "a workspace for its dependencies, not for a suite of its own: its tests sit in "
+      + "providers/<name>/test like every other adapter's and run with them. A script here would "
+      + "split one corpus across two mechanisms.",
+  },
+];
+
+/**
+ * The corpora, discovered from the manifest rather than listed.
+ *
+ * `providerFiles` is injectable for one reason: the exemption check below compares the covering
+ * corpus's file list against the workspace's own directory, and if both are always read from the
+ * same place the comparison can never fail — coverage in appearance with nothing underneath. The
+ * state worth refusing is a NARROWED corpus, which is an edit to `providerTestFiles`, so an arm has
+ * to be able to hand in a narrowed list and see the refusal.
+ */
+export function plan(root = ROOT, { providerFiles } = {}) {
+  const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const workspaces = manifest.workspaces ?? [];
+  const corpora = [];
+  const faults = [];
+
+  for (const ws of workspaces) {
+    let scripts = null;
+    try { scripts = JSON.parse(readFileSync(join(root, ws, "package.json"), "utf8")).scripts ?? {}; }
+    catch { scripts = null; }
+    // A DECLARED WORKSPACE WITH NO READABLE MANIFEST IS A FAULT, not a skip. The old command could
+    // not tell this apart from a workspace that simply had nothing to run.
+    if (scripts === null) { faults.push(`${ws} is a declared workspace and its package.json could not be read`); continue; }
+
+    if (scripts["test:full"]) {
+      corpora.push({ name: ws, kind: "workspace", argv: ["npm", "run", "test:full", "-w", ws] });
+      continue;
+    }
+
+    const cover = COVERED_ELSEWHERE.find((c) => c.workspace === ws);
+    if (!cover) {
+      faults.push(`${ws} is a declared workspace and defines no \`test:full\` script. Either give it `
+        + `one, or add it to COVERED_ELSEWHERE in scripts/test-full.mjs naming the corpus that runs `
+        + `its tests — which is checked, so the claim has to be true.`);
+      continue;
+    }
+    corpora.push({ name: ws, kind: "covered", cover });
+  }
+
+  const files = providerFiles ?? providerTestFiles(root);
+  corpora.push({
+    name: "providers",
+    kind: "files",
+    files,
+    argv: ["node", "scripts/test-run.mjs", "node", "--test", ...files],
+  });
+
+  // ── THE EXEMPTIONS, CHECKED ────────────────────────────────────────────────────────────────────
+  for (const c of corpora.filter((x) => x.kind === "covered")) {
+    const covering = corpora.find((x) => x.name === c.cover.corpus);
+    if (!covering || !Array.isArray(covering.files)) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, and this `
+        + `command has no such corpus with a file list to check that against.`);
+      continue;
+    }
+    const own = covering.files.filter((f) => f.startsWith(c.name + "/"));
+    // BOTH HALVES. A workspace that lost its own tests would pass a check that only asked whether
+    // the covering corpus was missing any of them, because nothing is missing from nothing.
+    const here = existsSync(join(root, c.name, "test"))
+      ? readdirSync(join(root, c.name, "test")).filter((f) => f.endsWith(".test.mjs")).length : 0;
+    if (!here) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, but it has `
+        + `no test files of its own, so that claim covers nothing. Remove the entry or restore the tests.`);
+    } else if (own.length !== here) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, which reaches `
+        + `${own.length} of its ${here} test file(s). The exemption is no longer true.`);
+    }
+    c.reaches = own.length;
+    c.hasTests = here;
+  }
+
+  return { corpora, faults };
+}
+
+function main() {
+  const only = (() => { const i = process.argv.indexOf("--only"); return i === -1 ? null : process.argv[i + 1]; })();
+  const listOnly = process.argv.includes("--list");
+  const { corpora, faults } = plan();
+
+  // FAULTS BEFORE ANYTHING RUNS. A missing corpus discovered after a green suite reads as an
+  // afterthought; discovered first, it is the answer.
+  if (faults.length) {
+    console.error(`\ntest-full: ${faults.length} declared workspace(s) this command cannot account for:\n`);
+    for (const f of faults) console.error(`  - ${f}`);
+    console.error("");
+    process.exit(1);
+  }
+
+  const chosen = only ? corpora.filter((c) => c.name === only || c.name.endsWith("/" + only)) : corpora;
+  if (only && !chosen.length) {
+    console.error(`test-full: no corpus named ${only}. Known: ${corpora.map((c) => c.name).join(", ")}`);
+    process.exit(2);
+  }
+
+  if (listOnly) {
+    for (const c of chosen) {
+      console.log(c.kind === "covered"
+        ? `  ${c.name}: covered by the ${c.cover.corpus} corpus (${c.reaches}/${c.hasTests} file(s))`
+        : `  ${c.name}: ${c.kind === "files" ? `${c.files.length} file(s)` : "workspace script"}`);
+    }
+    return;
+  }
+
+  const ran = [];
+  for (const c of chosen) {
+    if (c.kind === "covered") { ran.push({ ...c, status: "covered" }); continue; }
+    console.log(`\n──── ${c.name} ────`);
+    // STDIO INHERITED, NOT CAPTURED. CI reads the child stream for the corpus-guard markers, and a
+    // runner that buffered its children would take those markers out of the log the check greps.
+    const r = spawnSync(c.argv[0], c.argv.slice(1), { cwd: ROOT, stdio: "inherit" });
+    ran.push({ ...c, status: r.status === 0 ? "ok" : "FAILED", code: r.status });
+  }
+
+  // ── THE SUMMARY, AT THE END, ON STDOUT ─────────────────────────────────────────────────────────
+  // The point of the whole file. A reader who scrolls to the bottom of a long run sees every corpus
+  // this command knows about and what became of it, so "the full suite is green" is a claim they can
+  // check rather than one they have to trust.
+  console.log(`\n──── what test-full ran ────`);
+  for (const c of ran) {
+    if (c.status === "covered") {
+      console.log(`  covered  ${c.name} — ${c.hasTests} file(s), run by the ${c.cover.corpus} corpus: ${c.cover.why}`);
+    } else {
+      const n = c.kind === "files" ? `${c.files.length} file(s)` : "workspace suite";
+      console.log(`  ${c.status === "ok" ? "ran    " : "FAILED "}  ${c.name} — ${n}${c.code ? ` (exit ${c.code})` : ""}`);
+    }
+  }
+  const bad = ran.filter((c) => c.status === "FAILED");
+  console.log(bad.length ? `\n${bad.length} corpus/corpora failed.` : `\nEvery corpus above was run or accounted for.`);
+  if (bad.length) process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/test-run.mjs

@@ -223,6 +223,22 @@ const providerChosen = ["CLEAROTRON_DATABASE"]
   .some((n) => String(process.env[n] ?? "").trim() !== "");
 if (!providerChosen) process.env.CLEAROTRON_DATABASE = "corsearch";
 
+// ── THE SUITE'S OWN BRAND-OWNER FIXTURES, ASKED FOR IN ONE PLACE ──────────────────────────────────
+//
+// Three profiles in `driver/profiles/` are the suite's, and a resolved roster no longer offers them:
+// an outside user's brand-owner picker listed them on a `git clone` install, where the packaging
+// exclusion that protects the tarball does not apply. They are marked `testFixture` and the loader
+// refuses them on every route.
+//
+// The checks still need them, under the same keys the baselines use, and most do not call the loader —
+// they exercise code that does, so there is no argument to pass. One variable here is the whole ask,
+// and it is visible: a reader of this file can see that the suite runs against a roster no install
+// resolves, which is a thing worth being able to see rather than a default nobody set.
+process.env.CLEAROTRON_TEST_FIXTURE_PROFILES ??= "1";
+// The demo account is refused from a fresh install's roster for the same reason and by the same
+// mechanism; the suite asks for it here, once, so no check has to know it was hidden.
+process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
+
 // ── A PARTLY-BLIND SUITE IS NOT A FAILING SUITE ────────────────────────────────────────────
 //
 // `git worktree add` gives you no `node_modules`, nothing in this repo creates one, and the tracker asks

package/shared/README.md

@@ -25,7 +25,8 @@ resolves the running commit for artifact provenance, but it cannot be the shared
 | `listen.mjs` | The one place a bind failure becomes a sentence rather than a stack trace. |
 | `driver-dir.mjs` | Where a run's `_driver/` is: the name, the path, and the one creation call. Product code no longer builds it by hand, so the directory's location — and one day its mode — is a decision in one place rather than a convention in 1123. |
 | `site-nav.mjs`, `anon-overlay.mjs` | The single top nav shared by the internal staff pages, and the display-only overlay that masks client names and marks so those pages can be screen-shared. |
-| `identifier-scan.mjs`, `identifier-blocklist.mjs`, `vetted-identities.mjs` | One matcher, one name table, one list of declared exceptions — shared by the guard that sweeps the tracked tree and the scan that sweeps the whole history. |
+| `identifier-scan.mjs`, `identifier-sentinels.mjs`, `vetted-identities.mjs` | One matcher, one name table, one list of declared exceptions — shared by the guard that sweeps the tracked tree and the scan that sweeps the whole history. The real table is private; the sentinels are what make a zero from that sweep mean something. |
+| `reference-guard-classes.mjs` | What a public tree must not acquire, as one table: citations, account names, home directories on the build machines, private repository names, this project's own words for how it is organised, and both attribution trailers. Read by the diff guard in `scripts/added-reference-check.mjs` and by the per-file floor beside it. |
 
 `brand/assets/` holds the vendored logo SVGs. `tools/` holds the two brand-system generators — see
 [`tools/README.md`](tools/README.md).

package/shared/anon-overlay.mjs

@@ -6,7 +6,7 @@
 // Feedback console went with the quality subsystem, so two of those five had not rendered for
 // months. Lets us screen-share the site without
 // revealing real client names or the marks being cleared: client names map to descriptive aliases
-// (e.g. Zephyr Beverages → "Beverage company") and marks blur out, behind ONE site-wide toggle (no
+// (e.g. Coastline Drinks → "Beverage company") and marks blur out, behind ONE site-wide toggle (no
 // hover-reveal). Display-only — it never mutates stored data, run metadata, or form values.
 //
 // SHAPE (mirrors site-nav.mjs's NAV_CSS/siteNav split):
@@ -19,7 +19,7 @@
 //   • anonToggle(cfg?)   — the toggle button markup for the nav ('' when disabled).
 //
 // Tagging conventions the browser overlay understands:
-//   <span data-anon="client" data-anon-key="zephyr">Zephyr Beverages</span>  → text swapped for the alias
+//   <span data-anon="client" data-anon-key="coastline">Coastline Drinks</span>  → text swapped for the alias
 //   <span data-anon="mark" data-anon-key="…" data-anon-run="…">NOVA PULSE</span> → blurred (unless exempt)
 //   <a data-anon-href data-anon-key="…" data-anon-run="…" href="…">     → href neutralised to # (unless exempt)
 // A run/client is EXEMPT (shown real) when its key ∈ demoAllow.clientKeys or its run matches
@@ -81,7 +81,7 @@ const OVERLAY_BODY = `(function(){
   var DEAD_TITLE = "hidden in privacy mode — toggle Privacy OFF to open";
   var DA = C.demoAllow || {clientKeys:[],runs:[]};
   // Case-insensitive client lookup, and the reason it is not redundant: surfaces tag rows by profile
-  // KEY ("zephyr") and by display NAME ("Zephyr"), so lowercasing both makes a single-token name
+  // KEY ("coastline") and by display NAME ("Coastline"), so lowercasing both makes a single-token name
   // resolve to its key's alias. The two surfaces that tagged by NAME were Quality and Feedback, both
   // retired (tracker issue 265) — the fold stays because it is what makes the lookup total over either spelling,
   // not because those pages are coming back.

package/shared/browser-temp-root.mjs

@@ -0,0 +1,142 @@
+// 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
+// browser-temp-root.mjs — give a browser launch its own temp root, so an untidy exit leaks nothing shared.
+//
+// ── WHAT LEAKS, AND WHY IT IS NOT THE PROFILE DIRECTORY ───────────────────────────────────────────
+//
+// Chrome does not keep its process-singleton lock in `--user-data-dir`. It creates a directory named
+// `com.google.Chrome.XXXXXX` in the system temp directory, holding `SingletonCookie` and a
+// `SingletonSocket` unix socket, and symlinks the profile's entry at it. The reason is length: a
+// profile path may be too long for a unix socket, so the lock is shortened through the temp root.
+//
+// Every launcher here already removes its own profile directory. None of them could remove that one,
+// because none of them knows its name. Measured on a development machine 2026-09-09: 4,855 such
+// directories under one shared temp root, the oldest five days old, still accumulating — the residue
+// of runs that ended without running their cleanup, mostly cancelled continuous-integration jobs.
+//
+// The fix is not to find and delete them. It is to stop them being shared: the directory is created in
+// `GetTempDir()`, which honours `TMPDIR`, so a run that exports its own temp root gets its own copy of
+// the lock inside it and takes it away when the root goes.
+//
+// ── THE BYTE BUDGET, WHICH IS WHY THIS FILE REFUSES RATHER THAN TRUSTS ────────────────────────────
+//
+// A unix socket address is a fixed 108-byte field, so the socket path must fit in 107 bytes plus a
+// terminator. The lock directory and socket name add a fixed 41 characters to the temp root, leaving
+// 66 for the root itself. One character more and Chrome does not degrade — it aborts, with a fatal
+// log line about the socket path and a core dump.
+//
+// That failure is why the check below exists. A crash in a continuous-integration step, reported as a
+// core dump, is not something a reader connects to the length of a checkout path; and the length is
+// not a constant of this project, because a run can be rooted anywhere a caller or a runner puts it.
+// So the budget is asserted at the point the root is chosen, and the refusal states the length it
+// measured, the limit, and the path — which is the whole of what a reader needs to fix it.
+//
+// The boundary is measured, not derived: walking root lengths across it, 66 starts and 67 aborts.
+import { mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeOnExit } from "./reap-on-exit.mjs";
+
+/** A unix socket address field is 108 bytes; the last is the terminator. */
+export const SUN_PATH_MAX = 107;
+
+/** `/com.google.Chrome.XXXXXX/SingletonSocket` — what the lock adds to the temp root. */
+export const LOCK_SUFFIX = "/com.google.Chrome.XXXXXX/SingletonSocket";
+
+/** The longest temp root a browser can be launched under. */
+export const MAX_ROOT_LENGTH = SUN_PATH_MAX - LOCK_SUFFIX.length;
+
+/**
+ * The root's own prefix, and it is SHORT ON PURPOSE — this is the one lever on the budget.
+ *
+ * Every character here is spent on every browser run, and roots nest: under the suite runner the
+ * ambient temp directory already carries one `ct-testrun-XXXXXX` level before this is appended.
+ * Measured on a development machine 2026-09-09, ambient temp 18 characters:
+ *
+ *              root length     worst case with a 22-character name in the root   with this prefix
+ *   ambient        18                       47  (19 to spare)                     29  (37 to spare)
+ *   one runner     36                       65  (ONE to spare)                    47  (19 to spare)
+ *   nested         54                       83  (refuses)                         65  (1 to spare)
+ *
+ * The middle row is why this is not cosmetic. Naming the root after the check spent the budget on a
+ * label, and left an ordinary single-level suite run one character from refusing — a host with a
+ * temp directory one character longer, or this one renamed a level deeper, and every browser check
+ * would refuse at once while the tree looked broken. So the root is named for what it IS, and the
+ * check that made it is named by the directory INSIDE it, where length costs nothing.
+ *
+ * A leaked root is still sweepable by name, which was the point of naming it at all, and now it is
+ * attributable too: open it and the profile directory says which check left it.
+ */
+export const ROOT_PREFIX = "ctb-";
+
+/**
+ * Why `dir` cannot be a browser temp root, or `null` if it can.
+ *
+ * Returned rather than thrown so a caller can decide: a check that has already produced a result
+ * should say this and exit, not lose the result to an exception.
+ */
+export function rootRefusal(dir) {
+  if (typeof dir !== "string" || dir === "") return "a browser temp root must be a non-empty path";
+  if (dir.length <= MAX_ROOT_LENGTH) return null;
+  return (
+    `browser temp root is ${dir.length} characters and the limit is ${MAX_ROOT_LENGTH}: ${dir}\n` +
+    `  A browser writes its process-singleton socket at <root>${LOCK_SUFFIX}, and a unix socket ` +
+    `address holds ${SUN_PATH_MAX} characters. Over that the browser aborts with a fatal error about ` +
+    `the socket path rather than reporting anything this check could read.\n` +
+    `  Run from a shorter path, or set TMPDIR to one.`
+  );
+}
+
+/** The refusal as an exception, for a caller with nothing to lose by throwing. */
+export function assertRootFits(dir) {
+  const why = rootRefusal(dir);
+  if (why) throw new Error(why);
+  return dir;
+}
+
+/**
+ * A temp root for one browser run, removed when this process exits by any route it can observe.
+ *
+ * Rooted at the ambient temp directory rather than anywhere relative to the checkout, and that is a
+ * decision rather than a convenience: the ambient root is short by construction, while a checkout,
+ * a worktree or a per-session scratch directory is routinely past the budget above. Nesting is
+ * still correct — under a test runner that has already exported its own root, this lands inside it
+ * and is carried away with it.
+ */
+export function browserTempRoot() {
+  const root = mkdtempSync(join(tmpdir(), ROOT_PREFIX));
+  assertRootFits(root);
+  removeOnExit(root);
+  return root;
+}
+
+/**
+ * The environment a browser must be spawned with so its singleton lock lands under `root`.
+ *
+ * `TMPDIR` is the whole mechanism, so this refuses rather than passing a root that cannot work.
+ */
+export function browserEnv(root, env = process.env) {
+  assertRootFits(root);
+  return { ...env, TMPDIR: root };
+}
+
+/**
+ * A temp root and a profile directory inside it, plus the environment to spawn with.
+ *
+ * The profile goes INSIDE the root so one removal covers both. Several call sites used to make the
+ * profile directly in the shared temp directory and remove it on their success path; that left the
+ * singleton lock behind on every other path, which is the leak this module exists for.
+ */
+export function browserRun(label = "browser") {
+  const root = mkdtempSync(join(tmpdir(), ROOT_PREFIX));
+  assertRootFits(root);
+  const keep = removeOnExit(root);
+  // The CALLER'S NAME GOES HERE, inside the root, where it costs nothing against the socket budget.
+  // Callers pass the name they used to prefix the root with, trailing dash and all, so this reads as
+  // `<root>/home-check` and an operator opening a leaked root learns which check left it.
+  const profile = join(root, label.replace(/-+$/, "") || "browser");
+  mkdirSync(profile, { recursive: true });
+  // `keep` deregisters the root from the exit sweep. A caller with a `--keep` flag MUST call it, or
+  // the flag reads as working while the directory it promised goes at exit.
+  return { root, profile, env: browserEnv(root), keep };
+}

package/shared/checkout-move.mjs

@@ -9,7 +9,7 @@
 // so that one line decides which tree the whole deployment executes — and connect said nothing about
 // having written it.
 //
-// Driven on testuser: a lane made a worktree to test a branch, ran `connect` from it once, and
+// Driven on the test deployment: a lane made a worktree to test a branch, ran `connect` from it once, and
 //
 //   · the next deploy tick fast-forwarded the DETACHED worktree and failed with "You are not currently
 //     on a branch" — a message about branches, for a box that was silently a merge behind; and

package/shared/client-door.mjs

@@ -41,6 +41,7 @@
 
 import { join } from "node:path";
 import { challengeVerdict, blockedByAccessChallenge, challengeNote } from "./mcp-challenge.mjs";   // — F57
+import { whatHoldsPort } from "./os-advice.mjs";
 
 /** The unit that runs the client door. Installed like any other; started only by this module. */
 export const CLIENT_DOOR_UNIT = "clearotron-client-mcp.service";
@@ -162,7 +163,7 @@ export function clientDoorState({ env = {}, unitDir, exists, active = null, list
   const standing = fenceOn && unitInstalled;
   // ── CONFIGURED IS NOT RUNNING ──────────────────────────────────────────────
   //
-  // Measured by role-e2e: a `connect` that died at `daemon-reload` had ALREADY written the denylist and
+  // Measured in testing: a `connect` that died at `daemon-reload` had ALREADY written the denylist and
   // installed both unit files, and `doctor` then said "the client door is on" while the unit was
   // inactive and nothing listened on its port. The trigger was a shell without a session bus, which is
   // not the product's fault — but any failure at that step leaves the same half-applied state
@@ -187,7 +188,7 @@ export function clientDoorState({ env = {}, unitDir, exists, active = null, list
  * FIVE answers, and the two that matter are the two the caller used to get wrong in opposite directions.
  *
  * CONFIGURED IS NOT RUNNING. A `connect` that died at `daemon-reload` has already
- * written the fence and placed both units, so every angle reads as set up; role-e2e measured `doctor`
+ * written the fence and placed both units, so every angle reads as set up; testing measured `doctor`
  * saying "the client door is on" over an inactive unit with nothing on its port. That state is a
  * problem and it is the reason this function exists.
  *
@@ -278,7 +279,7 @@ export function describeDoorState(door, {
           + "That is very likely why it cannot start: the product's ports are fixed defaults, so another "
           + "install or a stray process holds it, and the unit fails over and over against a port it will "
           + `never get. Find the holder before re-applying anything — \`${startCmd}\`'s own refusal names `
-          + "the port and the variable, and `ss -ltnp` names the process." };
+          + `the port and the variable, and \`${whatHoldsPort("<the door's port>")}\` names the process.` };
     }
     if (looping) {
       return { level: "problem",

package/shared/customer-store.mjs

@@ -7,7 +7,7 @@
 // `process.env.PROFILE_DIR || join(HERE, "profiles")` while the runs, the roster, the account picker and
 // the artifacts door read `CLEAROTRON_CUSTOMERS_DIR`. Nothing set `PROFILE_DIR` — not `onboard`, not
 // `.env.example`, not the box's own env — so the settings surface served the product's BUNDLED DEMO
-// BUNDLE (aurora, generic, petcary, zephyr) while the runs served the real store.
+// BUNDLE while the runs served the real store.
 //
 // WHAT THE CLIENT SAW: every brand owner added the documented way was "These settings are not available
 // to you." The clearance itself submitted and ran under their framework. Only the surface that

package/shared/identifier-scan.mjs

@@ -13,7 +13,7 @@
 // So the rules live here and nowhere else. Anything that wants to know whether a line is clean imports
 // from this file.
 //
-// THE TABLE IS NOT HERE. shared/identifier-blocklist.mjs owns the names (sentinels, or sentinels ∪ the
+// THE TABLE IS NOT HERE. shared/identifier-sentinels.mjs owns the names (sentinels, or sentinels ∪ the
 // private roster). This file owns only the matching — it names no identity of its own beyond the
 // platform tokens ALLOWED_CONTEXT has to spell out, which is why it declares itself in
 // DECLARATION_SOURCES.

package/shared/install-auth.mjs

@@ -124,3 +124,38 @@ export function describeAuthGaps({ gaps, modes }, envFile) {
   }
   return out;
 }
+
+// ── WHAT PUTS SOMETHING IN FRONT OF A DOOR ───────────────────────────────────────────────────────────
+//
+// A different question from the one above, and kept apart from it deliberately: `authRequirements`
+// answers "what will this unit refuse to start without", which includes values that say nothing about
+// what is in front of it — a grants file, a local passphrase user, an allowed-domain list. This answers
+// "does something OUTSIDE this deployment resolve to these port numbers", which is the only question a
+// launcher may move a door on.
+//
+// Every name here is an alternative in some door's `oneOf`: a Cloudflare Access team, or that door's own
+// OIDC issuer. The AUDIENCES are deliberately absent — they are `all` entries, not alternatives, and an
+// audience set with neither a team nor an issuer refuses to start on every face, so it can never be the
+// only evidence of a proxy.
+//
+// THE CLIENT DOOR HAS ITS OWN ISSUER SPELLING and it is not legacy: `mcp-server/http-server-client.mjs`
+// reads `CLIENT_MCP_OIDC_ISSUER || TRADEMARK_MCP_OIDC_ISSUER`, and its fail-closed admits a start on the
+// client spelling alone with no team set. A deployment fronting only its client door that way once read
+// as unfronted here, which is the state that would have moved a door behind a proxy addressed to the old
+// number — up, and unreachable.
+//
+// An arm holds this list to the doors themselves rather than to this comment: it reads the entrypoints
+// `bin/start.mjs` spawns and asserts every team-or-issuer name they read appears below.
+export const FRONTING_VARIABLES = Object.freeze([
+  "CF_ACCESS_TEAM",
+  "PORTAL_OIDC_ISSUER",
+  "TRADEMARK_MCP_OIDC_ISSUER",
+  "CLIENT_MCP_OIDC_ISSUER",
+]);
+
+/**
+ * The fronting values this environment has set — empty means nothing outside resolves to these doors.
+ *
+ * @returns {string[]} the names that are set, in the order above
+ */
+export const frontingVariablesSet = (env = {}) => FRONTING_VARIABLES.filter((k) => SET(env, k));

package/shared/invocation.mjs

@@ -39,6 +39,7 @@
 import { existsSync } from "node:fs";
 import { basename, sep } from "node:path";
 import { INSTALL_DIR, inspectShim, pathPosition, shimDir, shimPath } from "./verb-shim.mjs";
+import { chdirPrefix } from "./os-advice.mjs";
 
 /**
  * Filesystem reads, injectable so the arms can drive a machine that is not this one.
@@ -92,6 +93,34 @@ export function standFrom(dir) {
   return at === -1 ? s : s.slice(0, at);
 }
 
+/**
+ * WHICH ROUTE THIS INSTALL ARRIVED BY — a package, or a source checkout.
+ *
+ * The setup wizard has two spellings and only one of them works for any given reader. Someone who ran
+ * `npm i clearotron` has no package scripts, so `npm run setup` is a command they cannot type; someone
+ * working in a clone of the source has the scripts but no `clearotron` binary linked for them, because
+ * npm links a package's bin for its dependencies and never for itself. Naming one of the two on a
+ * screen is a coin flip, and the screen that names it is read by people who have just installed and
+ * have nothing else to go on.
+ *
+ * The answer is a property of where this file sits on disk, so it is derived from that. A package —
+ * local or global — is unpacked inside a `node_modules` directory; a checkout is not. `standFrom`
+ * already draws that line for the sibling question of where to stand, and reusing it is deliberate:
+ * two predicates for "am I a package" would be two chances to disagree.
+ *
+ * NO PATH IS RETURNED, and that is the point of splitting it out from `invocationForm`. That function's
+ * `prefix` can be `cd /srv/whatever && npx `, which is the server's own layout, its account name and
+ * its directory structure. This answers the same question with a word, so the answer can travel to a
+ * browser without carrying the machine with it.
+ *
+ * @param {string} dir  where this module is installed
+ * @returns {'packaged'|'checkout'}
+ */
+export function installRoute(dir = INSTALL_DIR) {
+  const s = String(dir ?? "");
+  return standFrom(s) === s ? "checkout" : "packaged";
+}
+
 /**
  * WHERE npm PUT THE EXECUTABLE for a GLOBAL install of this package —.
  *
@@ -181,7 +210,10 @@ export function invocationForm(env = process.env, io = FS, installDir = INSTALL_
   // to fix it — through the very shim it had just called broken. The advice for repairing a route
   // cannot travel that route. Both remaining forms go around it.
   return {
-    form: "in-place", prefix: `cd ${standFrom(installDir)} && npx `, shim: path, dir,
+    // THE SEPARATOR IS THE PART THAT FAILS OFF POSIX, not the path. `chdirPrefix` answers for the
+    // shell the reader is actually in; on Windows PowerShell 5.1 there is no `&&` at all, so this
+    // line was a parse error there before its backslashes mattered. Reported from a real run.
+    form: "in-place", prefix: `${chdirPrefix(standFrom(installDir))}npx `, shim: path, dir,
     onPath: false, shadowedBy: null, shimKind: shim.kind, otherInstall: shim.installDir,
     staleInterpreter: shim.interpreterMissing === true ? shim.interpreter : null,
   };