clearotron 0.2.1 → 0.2.3

package/shared/identifier-scan.mjs

@@ -288,7 +288,7 @@ const COMMENT_LINE = /^\s*(\/\/|#|\*|<!--)/;
 // address, and a reader sent looking for one would be looking in the wrong place.
 // `contact` joins on the owner's ruling of 2026-08-24: the launch documents collapsed to ONE public
 // mailbox, and counsel's pack (ADDITIONAL-TERMS.md, NOTICES.md, TRADEMARKS.md) prints it. Added here in
-// the same PR that introduced it, per 's rule above — a ruled mailbox joins this list, it never gets
+// the same PR that introduced it, per the rule above — a ruled mailbox joins this list, it never gets
 // a domain exemption. `interested` and `security` stay: they are no longer printed by any shipping
 // document, but removing a localpart from an allowlist is how a future document that uses one again
 // fails for a reason nobody expects.
@@ -390,7 +390,7 @@ export function scanOperatorIdentity(files, readFn, { withheld = () => false } =
 // ──: THE RETIRED PLATFORM ───────────────────────────────────────────────────────────────────
 //
 // The sixth pattern, and the narrowest: one token, matched case-insensitively, anywhere in a tracked
-// file. It is here rather than in a one-off script because 's last scope line asks for exactly
+// file. It is here rather than in a one-off script because the last scope line asks for exactly
 // this — "extend the battery so this class cannot return" — and because the class it guards is the
 // one the other five provably could not see. An integrator platform's name is not a person, not a
 // home path, not a classification stamp, not an audience, and not a vendor standing where a category
@@ -439,7 +439,7 @@ export const namesRetiredPlatform = (text) => RETIRED_PLATFORM.test(String(text
 // reasonably concludes they need a Cloudflare account.
 //
 // WHY A QUALIFIER RATHER THAN A BAN. The vendor name must keep appearing — a runbook worked through
-// one real proxy end to end is worth more to an installer than an abstract one, and 's rewrite
+// one real proxy end to end is worth more to an installer than an abstract one, and the rewrite
 // deliberately kept it. What must not happen is the name standing where the CATEGORY belongs. So the
 // rule is: name the vendor as much as you like, provided the line (or the one either side of it) says
 // it is an example, a reference, or what THIS deployment happens to use.

package/shared/invocation.mjs

@@ -92,6 +92,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 —.
  *
@@ -263,7 +291,7 @@ export const bareInvocation = (verb) => `clearotron ${verb}`;
 /**
  * Refuse a prompt when there is nobody to answer it.
  *
- * — bb8's F14 item 5. `install` has said this since it was written; `connect`
+ * — found in review. `install` has said this since it was written; `connect`
  * and `disconnect` prompt through readline and did not, so piped or redirected they read EOF and took
  * it as an answer. `install`'s exit code and wording are the model, and this is that model shared
  * rather than copied a third time.

package/shared/names-in-force.mjs

@@ -43,6 +43,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_DEFAULT_AGENT",
   "CLEAROTRON_DELIVERY",
   "CLEAROTRON_DEMO",
+  "CLEAROTRON_DEMO_PROFILES",
   "CLEAROTRON_DISPATCH_RECORD",
   "CLEAROTRON_DOCTOR_ASSUME_PINNED",
   "CLEAROTRON_DUMP_JSON",
@@ -141,6 +142,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_REPLAY_SNAPSHOT",
   "CLEAROTRON_REPORTS_DIR",
   "CLEAROTRON_REPORTS_URL",
+  "CLEAROTRON_REQUESTER_WHATSAPP",
   "CLEAROTRON_REQUIRE_EXPLICIT_PORTS",
   "CLEAROTRON_RETRY_BACKOFF_MS",
   "CLEAROTRON_RUN_DIR",
@@ -161,6 +163,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_SUITE_TELEMETRY_DIR",
   "CLEAROTRON_SYNTHESIS_MODEL",
   "CLEAROTRON_TAINT_CHAIN",
+  "CLEAROTRON_TEST_FIXTURE_PROFILES",
   "CLEAROTRON_TURN_CAP",
   "CLEAROTRON_TURN_LOCK_POLL_MS",
   "CLEAROTRON_UNREACHABLE_SENIOR",
@@ -168,6 +171,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_WARM_RETRY",
   "CLEAROTRON_WATCH_",
   "CLEAROTRON_WHATIF_MAX_CONCURRENT",
+  "CLEAROTRON_WHATSAPP_OPERATOR_COPY",
   "CLEAROTRON_WORKSPACE_PREFIX",
   "CLEAROTRON_WORK_DIR",
   "CLEAROTRON_X",

package/shared/node-floor.mjs

@@ -0,0 +1,97 @@
+// 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
+//
+// THE MINIMUM NODE VERSION, READ FROM THE ONE PLACE THAT DECLARES IT.
+//
+// `package.json` says `engines: { node: ">=22.13.0" }`. npm reads that field, and so does everything
+// here. Nothing restates the number.
+//
+// WHY THIS FILE EXISTS RATHER THAN A CONSTANT. There was a constant: `NODE_FLOOR = 22` in bin/onboard.mjs,
+// compared as `Number(process.versions.node.split(".")[0]) >= NODE_FLOOR`. A major-only comparison
+// STRUCTURALLY CANNOT SEE A MINOR FLOOR, so 22.9.0 passed a check written for a 22.13.0 floor — the check said
+// `node 22.9.0` and a tick while npm, reading the same requirement from the same repository, printed
+// EBADENGINE for it. One requirement, two spellings, already disagreeing.
+//
+// The cost was a first-run failure nobody could diagnose: an engine door exited 1 on a machine below the
+// floor, and every check the product offers said the runtime was fine.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The declared range, verbatim, e.g. `">=22.13.0"`. Throws if the field is gone — an absent floor is a
+ *  packaging fault, not a licence to run on anything. */
+export function declaredRange(root = join(HERE, "..")) {
+  const range = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))?.engines?.node;
+  if (!range) throw new Error("package.json declares no engines.node — the runtime floor has no source");
+  return String(range);
+}
+
+/**
+ * `">=22.13.0"` → [22, 13, 0]. `">=22"` and `">=22.13"` are accepted too, with the absent parts read as
+ * zero, because that is what they mean and not a guess — and because the field is edited by whoever
+ * changes the floor, who should not have to know which spelling this reader was written against. A
+ * coordination failure between two people editing one number is the defect this whole file exists for.
+ *
+ * ONLY the `>=` family. A caret or tilde range, or an `||` union, THROWS rather than being interpreted:
+ * a floor read wrongly is worse than one not read at all, because it would silently pass every version
+ * and take every check built on it with it.
+ */
+export function floorOf(range) {
+  const m = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?\s*$/.exec(String(range).trim());
+  if (!m) throw new Error(`engines.node is ${range}, which this reader does not understand — expected ">=x", ">=x.y" or ">=x.y.z"`);
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+/**
+ * `"22.16.0"` → [22, 16, 0], ignoring any pre-release or build suffix. NULL when it cannot be read.
+ *
+ * Null rather than zeroes, and the difference is the whole of it: `[0, 0, 0]` compares as below every
+ * floor, so a version string this reader did not understand would REFUSE — and this file would become
+ * the reason an install fails on a Node that is probably fine. A parser gap must not become an outage.
+ * Found in review, 2026-09-08.
+ */
+export const partsOf = (v) => {
+  // THE `v` IS OPTIONAL AND MUST BE, because both spellings are in reach: `process.versions.node` has
+  // no prefix and `process.version` does. Without it a caller handed the prefixed form gets null,
+  // null passes, and an out-of-date runtime is waved through by the guard written to stop it — the
+  // permissive half of the same asymmetry, which is the direction that fails silently.
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+/** Is `current` at or above `floor`? ALL THREE PARTS, in order — the defect this replaces compared one. */
+export function meetsFloor(current, floor) {
+  const c = partsOf(current);
+  // AN UNREADABLE RUNNING VERSION PASSES, and that asymmetry is deliberate. The DECLARED range is our
+  // own manifest and throws loudly when it cannot be read, because that is a packaging fault we own.
+  // The running version is whatever the runtime reports, and refusing one we failed to parse would
+  // stop a working install over our own gap. Refuse only what we can show is below the floor.
+  if (!c) return true;
+  for (let i = 0; i < 3; i += 1) {
+    if (c[i] > floor[i]) return true;
+    if (c[i] < floor[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The whole answer, for a caller that wants to refuse.
+ *
+ * `current` and `root` are injected so a check can drive every side of this without a second Node
+ * installation — a floor guard that can only be exercised by running on an old runtime is one nobody
+ * ever sees fail.
+ */
+export function nodeFloorVerdict({ current = process.versions.node, root } = {}) {
+  const range = declaredRange(root);
+  const floor = floorOf(range);
+  return { ok: meetsFloor(current, floor), current, required: floor.join("."), range };
+}
+
+/** What a person is told, in one sentence, naming both versions. No stack, no advice they cannot act on. */
+export function nodeFloorRefusal(v) {
+  return `This needs Node ${v.required} or newer, and this is Node ${v.current}. `
+    + "Upgrade Node and run the command again — nothing else here will work until you do.";
+}

package/shared/product-owned-names.mjs

@@ -24,7 +24,7 @@
 // Add it here and nowhere else, and only if this product genuinely owns it. A prefix added to let one
 // awkward name through re-opens the gap for every future gather — the cost is not local.
 export const PRODUCT_NAME_PREFIXES = Object.freeze([
-  "PRELIM", "CLEAROTRON", "PORTAL", "TRADEMARK_MCP", "CLIENT_MCP", "CLIENT_ACCESS",
+  "CLEAROTRON", "CLEAROTRON", "PORTAL", "TRADEMARK_MCP", "CLIENT_MCP", "CLIENT_ACCESS",
   "CLIENT_CF", "PROFILE", "RECIPE", "MCP_A",
 ]);
 

package/shared/register-selection.mjs

@@ -31,7 +31,7 @@
 // `driver/run-requirements.mjs` derives from those two fields and never restates them.
 //
 // The vendor sign-up steps travel WITH the table rather than staying behind in the wizard: they are
-// facts about the register, the wizard is one reader of them, and tracker issue 100 asks for the same
+// facts about the register, the wizard is one reader of them, and the same steps are asked for on the same
 // steps on surfaces the wizard does not own.
 
 // The USPTO sizing figures are MEASURED and live in their own module; the warnings below quote them

package/shared/scope.mjs

@@ -39,7 +39,7 @@ export function isRevoked(jti, { denylistPath = process.env.TRADEMARK_MCP_TOKEN_
   let text;
   try { text = readFileSync(denylistPath, "utf8"); }
   catch (e) {
-    // FAIL CLOSED ( — bb8's F14; overwatch ruling, recorded on 1889 for the owner's
+    // FAIL CLOSED (found in review; ruled and recorded for the owner's
     // review with the reversal path, which is this function).
     //
     // This returned false — "not revoked" — on any unreadable list, and that is how a revoked key kept
@@ -64,7 +64,7 @@ export function isRevoked(jti, { denylistPath = process.env.TRADEMARK_MCP_TOKEN_
  *
  * NOT AN AUTHENTICATOR. This parses without verifying, which is safe for exactly one job: reading the
  * revocation handle out of our own `mintToken` output so `clearotron connect` can write it down
- * (, owner ruling: record key IDs, never secrets). Anything answering "is this token
+ * (owner ruling: record key IDs, never secrets). Anything answering "is this token
  * good" goes through `verifyToken`; a caller handing this function a token from the WIRE is the defect.
  *
  * Returns null rather than throwing on a malformed string — the caller is recording, and a record of
@@ -302,7 +302,7 @@ export const USER_ARTIFACTS = new Set(["report"]);
 //   SEALED  MODEL IDENTITY, BILLED COUNTS, and THE ENGINE'S JUDGMENT OF ITS OWN OUTPUT. Which model tier
 //           ran a stage and what it cost is the firm's cost structure, not an audit fact — and
 //           `withdrawn_reason` ("confabulated attribution") is an assessment of our own quality that the
-//           client has no counterpart for, already ruled un-forwardable (, scrub.mjs).
+//           client has no counterpart for, already ruled un-forwardable (scrub.mjs).
 //
 // That line is cheap to hold because the code had already drawn it: events.mjs says "Model identity is
 // deliberately NOT projected here: decision_timeline / run_changes are narrative surfaces", trace.mjs and
@@ -713,7 +713,7 @@ export function attributionOf(scope, onBehalfOf = null) {
   // the delegate does not widen what the token may do.
   const delegate = typeof onBehalfOf === "string" && onBehalfOf.trim() ? onBehalfOf.trim() : null;
   if (!delegate) return self;
-  // COUNTS AND IDENTIFIERS, NOT PROSE ('s scope note): this file is a matter record. A delegate
+  // COUNTS AND IDENTIFIERS, NOT PROSE (the scope note): this file is a matter record. A delegate
   // carrying whitespace, a colon or a newline would forge the compound form or spill a sentence into the
   // archive, so anything that is not a bare identifier is refused and the verified half stands alone.
   if (!/^[A-Za-z0-9._%+@-]{1,128}$/.test(delegate)) return self;
@@ -759,7 +759,7 @@ export function authorize(scope, toolName, args = {}) {
     }
     // The PREVIEW only, deliberately — the same line the internal branch draws below.
     //
-    // #53's defect was that the FREE call every principal makes first died on a message naming an
+    // The defect was that the FREE call every principal makes first died on a message naming an
     // internal doc, so that is the call the stamp exists to rescue. Extending it to start_run would
     // quietly remove a spend gate: an ops token's sub is often a connector name or "local", buildJob
     // fills forwarderEmail from `${forwarder}@example.com` when none is given, and the result is a real

package/shared/server-units.mjs

@@ -28,7 +28,7 @@
 // today and zero right ones tomorrow. `orphanReason` cannot discriminate either — all six carry one, and
 // `clearotron-client-mcp`'s used to say the opposite thing — never install it eagerly, because starting
 // it was the on-demand consent that opened client-account access. That row was rewritten on 2026-09-03
-// when the owner superseded the posture (, settled point 2), which does not rescue the
+// when the owner superseded the posture (settled point 2), which does not rescue the
 // rejected repair: the reason a skip-on-orphan filter fails is that `runsOn: []` records boxes MEASURED,
 // and every unit here starts life unmeasured.
 //
@@ -74,7 +74,7 @@ export const SERVER_INSTALL_SET = Object.freeze([
   // "On demand is fine" — starting the door WAS the consent that opened client-account access, so an
   // installer that placed it would have made that consent meaningless.
   //
-  // The owner superseded that knowingly (, settled point 2): the door auto-starts
+  // The owner superseded that knowingly (settled point 2): the door auto-starts
   // with the product and THE PER-ACCOUNT KEY IS THE GATE, not whether a process runs. A door with no
   // key issued refuses everything, which is the same protection with a different mechanism — and a
   // better one, because it does not depend on a reader finding a verb.
@@ -85,7 +85,7 @@ export const SERVER_INSTALL_SET = Object.freeze([
 ]);
 
 /**
- * Installed and enabled ONLY by `clearotron connect`, never by an install path (,
+ * Installed and enabled ONLY by `clearotron connect`, never by an install path (
  * owner ruling 2026-08-31). Named here so a reader of this file learns it exists and learns it is
  * excluded on purpose — an absence with no reason beside it is the thing this module is against.
  */
@@ -98,7 +98,7 @@ export const ON_DEMAND_UNITS = Object.freeze([]);
 /**
  * Which of the installed units a `--background` REFRESH must restart.
  *
- * — Hera's review of the F15 fix. `enable --now` on an ALREADY-ACTIVE unit is a
+ * — A review of that fix. `enable --now` on an ALREADY-ACTIVE unit is a
  * no-op, so a refresh over an updated checkout leaves the old process running the old files. The restart
  * loop that exists for exactly that named a hardcoded PAIR — the same pair the health check named, three
  * lines below it — with the same stale justification: "the oneshot and its triggers pick the new copies

package/shared/staff-domain.mjs

@@ -0,0 +1,154 @@
+// 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
+// staff-domain.mjs — what a staff-domain rule ADMITS, decided before one is written.
+//
+// `PORTAL_STAFF_DOMAINS` is a list of email domains, and every address at a listed domain that gets
+// past this instance's sign-in door is staff: it sees every brand owner on the instance
+// (driver/portal-access.mjs). That is a rule about a set of people, not about one person.
+//
+// The install used to build that rule by taking everything after the last `@` of the one address it
+// was given. On a laptop that address is `<account>@localhost` and the rule admits the one identity
+// that can sign in, which is why it was safe and why nobody looked at it again. Given a real address
+// the same line turns a person into their whole employer, or into every customer of a webmail
+// provider, with nothing said to the operator and nothing to undo. A stranger's install granted a
+// documentation domain that way, read its own settings page back, and reported it as a back door.
+//
+// So the derivation is classified before it is used, and there are three answers:
+//
+//   "narrow"    the domain cannot name a second person on this machine — `localhost`, or any bare
+//               hostname with no dot. Deriving a rule from it is what it always was: safe, silent.
+//   "public"    a webmail or shared provider. Never a staff rule: it would admit strangers, and no
+//               deployment can want it. Refused outright, and the refusal names the domain.
+//   "reserved"  a domain reserved for documentation and testing (RFC 2606). Nobody's real mail lives
+//               there, so a rule built from one is always an address somebody typed as a placeholder.
+//               Refused for the same reason, with a different sentence, because the remedy differs.
+//   "wide"      an ordinary routable domain. It may well be the right rule — it is how a firm admits
+//               its own lawyers — but it admits people the operator has not met, so it is stated in
+//               the words the settings page will use and confirmed before it is written. It is never
+//               derived silently from one address.
+//
+// FAIL-CLOSED, in the direction of a smaller grant. A domain wrongly classified `public` refuses, and
+// the operator sets `PORTAL_STAFF_DOMAINS` themselves in one line — an explicit decision, recorded
+// where the settings page can name it. A domain wrongly classified `wide` asks a question. Neither
+// outcome grants anything, which is why the lists below are allowed to be short and stay short: the
+// `wide` branch is what actually protects an operator, and the lists only decide whether the product
+// asks a question or refuses to ask one.
+
+/** Last-@ semantics, matching driver/portal-access.mjs and shared/scope.mjs `isFirmDomain`. */
+export function domainOfEmail(email) {
+  const e = String(email ?? "").trim().toLowerCase();
+  const at = e.lastIndexOf("@");
+  return at > 0 ? e.slice(at + 1) : "";
+}
+
+/**
+ * Webmail and shared mailbox providers, exactly.
+ *
+ * Not a census of the internet, and deliberately not growing into one: an unlisted provider still
+ * lands in `wide`, where it is stated and confirmed rather than written silently. What this list buys
+ * is that the commonest addresses a person types — their own personal mail — are refused with a
+ * sentence about why, instead of being offered as a rule somebody might say yes to.
+ */
+export const PUBLIC_EMAIL_DOMAINS = Object.freeze(new Set([
+  "gmail.com", "googlemail.com", "icloud.com", "me.com", "mac.com",
+  "aol.com", "mail.com", "gmx.com", "gmx.de", "gmx.net", "web.de", "t-online.de",
+  "proton.me", "protonmail.com", "protonmail.ch", "pm.me", "tuta.io", "tutanota.com",
+  "fastmail.com", "fastmail.fm", "hey.com", "zoho.com", "hushmail.com",
+  "mail.ru", "inbox.ru", "list.ru", "bk.ru", "rambler.ru",
+  "qq.com", "163.com", "126.com", "sina.com", "naver.com", "daum.net",
+  "seznam.cz", "wp.pl", "o2.pl", "interia.pl", "libero.it", "virgilio.it", "tiscali.it",
+  "free.fr", "orange.fr", "wanadoo.fr", "laposte.net", "sfr.fr", "bbox.fr",
+  "comcast.net", "verizon.net", "att.net", "sbcglobal.net", "bellsouth.net", "cox.net",
+  "btinternet.com", "sky.com", "virginmedia.com", "ntlworld.com", "talktalk.net",
+  "bigpond.com", "optusnet.com.au", "shaw.ca", "sympatico.ca", "rogers.com",
+  "xs4all.nl", "ziggo.nl", "telenet.be", "uol.com.br", "bol.com.br", "terra.com.br",
+  "rediffmail.com", "yandex.com", "yandex.ru", "ya.ru",
+]));
+
+/**
+ * Providers that sell the same mailbox under a per-country domain.
+ *
+ * Matched on the FIRST label, so `yahoo.co.uk` and `yahoo.fr` are covered without listing every
+ * country. Kept to names that are a provider and nothing else — a first label like `free` or `orange`
+ * is a real company's name somewhere, so those stay in the exact list above.
+ */
+export const PUBLIC_EMAIL_FAMILIES = Object.freeze(new Set([
+  "yahoo", "ymail", "rocketmail", "hotmail", "outlook", "live", "msn", "gmx", "yandex", "googlemail",
+]));
+
+/**
+ * Reserved for documentation and testing — RFC 2606 §2 and §3.
+ *
+ * `example.com`, `example.net`, `example.org` and everything under them, plus the whole of the
+ * `.example`, `.invalid`, `.test` and `.localhost` top-level names. Real mail is never delivered to
+ * any of them, so an address at one is a placeholder somebody typed — which is exactly what happened.
+ *
+ * `localhost` ITSELF IS NOT HERE. A bare `localhost` is the local-account default and is classified
+ * `narrow` below; only `something.localhost` reaches this test.
+ */
+function isReservedDomain(domain) {
+  if (/^example\.(com|net|org)$/.test(domain)) return true;
+  if (/\.example\.(com|net|org)$/.test(domain)) return true;
+  const tld = domain.slice(domain.lastIndexOf(".") + 1);
+  return domain.includes(".") && ["example", "invalid", "test", "localhost"].includes(tld);
+}
+
+/** A domain that cannot name a second person on this machine: `localhost`, or any dotless hostname. */
+function isNarrowDomain(domain) {
+  return domain === "localhost" || domain === "localhost.localdomain" || !domain.includes(".");
+}
+
+/**
+ * What a staff rule built from this domain would admit.
+ *
+ * @param {string} domain a bare domain, already lowercased — `domainOfEmail` produces one.
+ * @returns {"narrow"|"public"|"reserved"|"wide"|""}  "" only when there is no domain to classify.
+ */
+export function classifyStaffDomain(domain) {
+  const d = String(domain ?? "").trim().toLowerCase();
+  if (!d) return "";
+  if (isNarrowDomain(d)) return "narrow";
+  if (isReservedDomain(d)) return "reserved";
+  if (PUBLIC_EMAIL_DOMAINS.has(d)) return "public";
+  if (PUBLIC_EMAIL_FAMILIES.has(d.slice(0, d.indexOf(".")))) return "public";
+  return "wide";
+}
+
+/**
+ * The rule in the words the settings page uses, so the operator recognises what they agreed to.
+ *
+ * ONE COMPOSER FOR BOTH SURFACES. The People & access screen renders "Anyone at <domain>" under a
+ * heading that calls it a config rule rather than a person, and describes staff as capable of seeing
+ * every brand owner. A consent prompt phrased any other way asks about one thing and shows another.
+ */
+export function staffGrantSentence(domain, { staffLabel = "Staff" } = {}) {
+  return `Anyone at ${domain} — a rule, not a person. ${staffLabel}: capable to see every brand owner `
+    + "on this instance.";
+}
+
+/**
+ * Why this domain cannot become a staff rule, and what to do instead.
+ *
+ * Returns null for a domain that CAN — `narrow` and `wide` are not refusals, and `wide` is answered by
+ * the confirmation the caller runs, not by this function.
+ */
+export function staffDomainRefusal(domain, { variable = "PORTAL_STAFF_DOMAINS" } = {}) {
+  const d = String(domain ?? "").trim().toLowerCase();
+  const verdict = classifyStaffDomain(d);
+  if (verdict === "public") {
+    return `${d} is a public email provider, so a staff rule built from it would admit anyone with an `
+      + `address there — not your colleagues. Refusing to write one.\n`
+      + `  Use an address at a domain your organisation controls, or set ${variable} yourself to the `
+      + "domain you mean.\n"
+      + "  If this machine is only yours, the local-account form takes no rule at all: leave the "
+      + "address as <account>@localhost.";
+  }
+  if (verdict === "reserved") {
+    return `${d} is reserved for documentation and receives no real mail (RFC 2606), so it is an `
+      + "address somebody typed as a placeholder rather than one that signs in. Refusing to build a "
+      + "staff rule from it.\n"
+      + "  Use the address you actually sign in with, or the local-account form <account>@localhost "
+      + "if this machine is only yours.";
+  }
+  return null;
+}

package/shared/store-in-repo.mjs

@@ -38,13 +38,34 @@
 // that does not exist yet is still misconfigured if it names another tree — the service would create it
 // and then fail every commit — so the lexical judgment stands where the filesystem cannot overturn it.
 
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, relative, isAbsolute } from "node:path";
 import { realpathSync } from "node:fs";
 
 /** `resolve`, then the symlink-resolved form when the path exists — null when it cannot be read. */
 const real = (p) => { try { return realpathSync(resolve(p)); } catch { return null; } };
 
-const within = (dir, root) => dir === root || dir.startsWith(root.endsWith("/") ? root : root + "/");
+// CONTAINMENT IS ASKED OF THE PATH LIBRARY, NOT OF THE STRING.
+//
+// This was `dir.startsWith(root + "/")`, with the separator written in. On Windows `resolve()` returns
+// backslashes, so `C:\…\config\recipes` does not start with `C:\…\config/` and a folder plainly inside
+// its parent read as OUTSIDE — an operator on a correct install was told their recipe store was outside
+// the repository root, and the saved-search door refused. Measured on his paths.
+//
+// The posix control passed throughout, which is why it survived: the string test is right on the platform
+// it was written on and wrong on the one nobody here runs.
+//
+// `relative` also settles two cases a prefix test gets wrong on Windows even with the separator fixed: a
+// different drive letter yields an absolute path rather than a `..` walk, and path comparison there is
+// case-insensitive in a way `startsWith` is not. A sibling directory whose name merely begins with the
+// root's — `config` and `configXX` — is still outside, which the old `+ "/"` also got right and any
+// replacement had to keep.
+// `impl` is the path module to ask, injected ONLY so a check can drive the Windows behaviour from a
+// Linux runner. That matters here more than usual: this defect was invisible on the platform every one
+// of us runs, and a guard that can only be exercised on Windows is a guard nobody will ever see fail.
+export const within = (dir, root, impl = { relative, isAbsolute }) => {
+  const rel = impl.relative(root, dir);
+  return rel === "" || (!rel.startsWith("..") && !impl.isAbsolute(rel));
+};
 
 /**
  * Is `storeDir` somewhere `git -C repoRoot add` could stage it?
@@ -226,7 +247,7 @@ export function commitWithAuditRow({ audit, gitCommit, files, message, by, row }
 //   portal-service   RECIPE_REPO_ROOT || <the profile repo root>   → the config store → saves work
 //   recipe-service   RECIPE_REPO_ROOT || join(HERE, "..")          → the PRODUCT CHECKOUT → FATAL
 //
-// Two ends of one contract measuring different things ('s class). The portal consulted the profile
+// Two ends of one contract measuring different things (the class). The portal consulted the profile
 // root as a second chance and the recipe-service did not, so one door came up and the other exited 1.
 //
 // AND THE DIVERGENT FALLBACK IS THE DANGEROUS ONE, which is why this is not merely tidying. The product
@@ -320,7 +341,7 @@ export function makeStoreCommit({ repoRoot, log = () => {}, what = "store", retr
       } catch (e) {
         const detail = detailOf(e);
         if (isTransientGitFault(detail) && attempt <= retries) { napping(waitMs * attempt); continue; }
-        // NAMED, not merely reported. 's line held that a failed commit is a permanent sync blocker
+        // NAMED, not merely reported. That line held that a failed commit is a permanent sync blocker
         // and belongs in the journal; it is no longer permanent — the next save completes it — but the
         // operator still needs to know WHICH fault, because a hook and a full disk want different people.
         log(`${what} COMMIT FAILED after the write landed — the save is LIVE and the paths are STAGED, `

package/shared/suite-census.mjs

@@ -15,7 +15,7 @@
 //
 // ── `.test(` IS NOT COUNTED, AND THAT IS THE WHOLE CALIBRATION ─────────────────────────────────────
 //
-// 's own thread records the miscount: 177 `RegExp.prototype.test` calls counted as subtests,
+// its own thread records the miscount: 177 `RegExp.prototype.test` calls counted as subtests,
 // genuine subtests ZERO. So this counts `assert.<something>` and a `test(` at the START of a line, and
 // nothing else. Two independent checks that it is calibrated: on the tree it was minted from, the
 // counted test sites match the EXECUTED totals at 415/415 for portal-ui, 382 against 386 for
@@ -105,7 +105,7 @@ export function rootScriptDisagreements(readManifest, declared = CENSUS_ROOT_SCR
 //
 // while 581 of 639 driver test files stop being collected. Both sides agreed because both sides
 // enumerate through the list ABOVE, and nothing in this repository opened a package.json. The census
-// was move-proof about the tests and blind to itself being pointed somewhere else, which is 's own
+// was move-proof about the tests and blind to itself being pointed somewhere else, which is its own
 // doctrine line: an enumerated check is blind to the thing moving; a discovered check is blind to
 // ITSELF moving.
 //
@@ -237,7 +237,7 @@ export function lossBetween(prevPerFile, nextPerFile) {
 }
 
 /**
- * tracker issue 205 — WHICH BUCKET EACH DIFFERENCE LANDS IN, and which of them refuses a re-stamp.
+ * WHICH BUCKET EACH DIFFERENCE LANDS IN, and which of them refuses a re-stamp.
  *
  * `lossBetween` above answers what MOVED. This answers what that MEANS, and it is a separate question
  * with a separate history. A rising skip count is a real difference and it used to refuse: it landed
@@ -343,7 +343,7 @@ export function countTestSites(text) {
  * The 1-based LINE of every assert site, in source order. One site per `assert.<x>` occurrence, so a
  * line carrying two of them appears twice — the same arithmetic `countTestSites` reports.
  *
- * 's fifth member needs the LINES, not just the total: a GATED arm — `if (!process.env.X) return;`
+ * That fifth member needs the LINES, not just the total: a GATED arm — `if (!process.env.X) return;`
  * at the top of a test body — leaves every token in place, so a count cannot see it and only "did this
  * line ever run" can. That question is answered by a coverage pass, and the two sides must ask it of the
  * SAME sites, so the rule lives here once rather than being re-typed against the same file.

package/shared/tty-style.mjs

@@ -2,7 +2,7 @@
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 // tty-style.mjs — weight where the meaning is, and NOTHING when the reader is not a terminal.
 //
-// ── why this exists (, owner ruling 2026-08-31) ────────────────────────────────────
+// ── why this exists (owner ruling 2026-08-31) ────────────────────────────────────
 //
 // "new terminals can do things like bold and colours etc — good formatting impresses people because it's
 // made clear to them someone put the time in." That is a product argument, not a decorative one: setup

package/shared/uspto-index-size.mjs

@@ -102,7 +102,7 @@ export const USPTO_PEAK_GB = Math.round((USPTO_INDEX_GB + USPTO_PEAK_WAL_GB) * 1
 //
 // It was pessimistic by 4x. Charging 1.0 demanded ~43.8 GB for a build whose index came to 10.1 GB, and
 // INSTALL.md told the reader to provision 60 GB. On the free tier that is the difference between "I can
-// try this on the disk I have" and "I cannot", which is the whole of 's Why.
+// try this on the disk I have" and "I cannot", which is the whole of the Why.
 //
 // Carried at 0.35 against 0.24 measured — a 46% margin, and the margin is doing real work rather than
 // decorating a guess:

package/shared/vacuous-pass.mjs

@@ -158,7 +158,7 @@ export function discoveredLoops(text) {
 
 // ── THE EARLY-RETURN HALF ──────────────────────────────────────────────────────────────────
 //
-// 's ruling names two shapes. `discoveredLoops` above is the loop half. This is the other, and
+// That ruling names two shapes. `discoveredLoops` above is the loop half. This is the other, and
 // the two are not alike enough to share a detector:
 //
 //   test("the tree is clean", () => {