clearotron 0.2.3 → 0.2.4

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/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.
@@ -209,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,
   };

package/shared/listen.mjs

@@ -65,9 +65,11 @@
 // WHAT THIS DELIBERATELY DOES NOT DO: look up who holds the port. Node cannot see another user's
 // process without privilege, and a probe that usually cannot look would print "no other instance" when
 // it means "could not check" — which is the same class of lie this whole issue is about. The EADDRINUSE
-// message already tells the operator `ss -ltnp`, which is the instruction that works.
+// message already tells the operator how to find the holder, in the shell they are actually in.
 
 /** The environment variable a shared box sets once to ban silent defaults for every service on it. */
+import { whatHoldsPort, stopThatProcess } from "./os-advice.mjs";
+
 export const REQUIRE_EXPLICIT_PORTS = "CLEAROTRON_REQUIRE_EXPLICIT_PORTS";
 
 /**
@@ -124,6 +126,40 @@ export function explicitPortRequiredMessage({ what, port, portVar }) {
  *             response-body and bundle assertion in the suite, so naming it is free and correct.
  *  `portFlag` an optional CLI equivalent, for the entry points that take one.
  */
+/**
+ * The first free port at or after `from`, or `null` when nothing in range is free — owner ruling,
+ * 2026-09-09.
+ *
+ * WHAT THIS IS FOR AND WHAT IT IS NOT. A collision on a DEFAULT port is this process discovering it
+ * guessed somebody else's address: nobody stated that number and nothing outside is addressed to it,
+ * so stepping to the next free one loses nothing. A collision on a port the reader SET is an address
+ * conflict they can reason about, and moving it silently would take the product away from where they
+ * pointed it. The caller decides which case it is; this only walks.
+ *
+ * AND IT IS ONLY EVER SAFE WHERE NOTHING FRONTS THESE DOORS. A proxy, an Access team or an OIDC issuer
+ * means something outside this process is addressed to these numbers, and a door that moved would be
+ * up and unreachable — the worst of the three outcomes, because it looks like success. That is the
+ * caller's question too, for the same reason: only it knows which deployment shape it is.
+ *
+ * `isFree` IS INJECTED and may be sync or async. A walker testable only by occupying real ports would
+ * be tested against whichever ports happened to be free on the machine that ran it, which is not a
+ * test of the rule.
+ *
+ * NULL RATHER THAN A GUESS when the range is exhausted. The caller then refuses on the port that was
+ * actually asked for, and the reader is told the truth — that address is taken — instead of being sent
+ * to one this could not prove was free either.
+ */
+export async function nextFreePort(from, isFree, { limit = 64, claimed = new Set() } = {}) {
+  for (let p = from + 1; p <= 65535 && p < from + limit; p += 1) {
+    // CLAIMED PORTS ARE NOT FREE, even though nothing is listening on them yet. The doors are chosen
+    // one after another and bound later, so two of them landing on one number is the same collision
+    // deferred — and the second to bind would be the one that failed.
+    if (claimed.has(p)) continue;
+    if (await isFree(p)) return p;
+  }
+  return null;
+}
+
 export function listenErrorMessage(err, { what, host, port, portVar, portFlag = null, portSource = null,
   portFile = null }) {
   const at = `${host}:${port}`;
@@ -160,8 +196,24 @@ export function listenErrorMessage(err, { what, host, port, portVar, portFlag =
             + `address — and had it been down just now, this process would have taken it silently. `
             + `Set ${portVar ?? "the port variable"} for this instance.\n`
           : "")
-        + `  See what holds it:  ss -ltnp 'sport = :${port}'   (or: lsof -i :${port})\n`
-        + `  Then stop that process${move ? `, or ${move}` : ""}.\n`
+        // ── THE HOLDER IS NOT ALWAYS SOMETHING TO KILL, AND THIS USED TO ASSUME IT WAS ─────────────
+        //
+        // "Then stop that process" is right for a stray second copy and wrong for the other common
+        // holder: an editor's port forward. A reader working over a remote session has the port
+        // forwarded to their laptop by the editor itself, so the thing holding it is the tool they are
+        // reading this message in — and stopping it drops the session that printed the advice.
+        //
+        // So the holder is named as a question rather than a verdict, moving THIS instance comes
+        // first among the remedies, and stopping the holder is offered second and only as the
+        // reader's own call. Nothing here claims to know which it is: that cannot be seen from
+        // inside this process, and the previous wording claimed it by implication.
+        + `  See what holds it:  ${whatHoldsPort(port)}\n`
+        + "  A forwarded port counts: an editor forwarding this port to your machine holds it exactly "
+        + "as a second copy would, and stopping that would end the session you are reading this in.\n"
+        + (move
+          ? `  Move this instance instead — ${move} — or, once you know what the holder is and that you `
+            + `do not need it, ${stopThatProcess()}.\n`
+          : `  Once you know what the holder is and that you do not need it, ${stopThatProcess()}.\n`)
         + whichFile
         + `  Refusing to start — it will NOT quietly move to another port, because whatever is in front `
         + `of it is still addressed to ${at}.`;

package/shared/names-in-force.mjs

@@ -8,7 +8,9 @@
 //
 //   node scripts/mint-names-in-force.mjs
 //
-// driver/test/retired-env-spellings.test.mjs regenerates this and refuses a stale copy.
+// CI refuses a stale copy, from the guards job: scripts/generated-files-are-current.mjs runs every
+// minter in scripts/ with --check. (This line used to name a test file that does not exist in this
+// tree, so the only thing that ever caught this drifting was a private control refusing to start.)
 
 export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_ACCESS_DOMAIN",
@@ -68,6 +70,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_GATHER_SESSION_KEY",
   "CLEAROTRON_HARD_MS",
   "CLEAROTRON_HTTP_TIMEOUT_MS",
+  "CLEAROTRON_IDENTIFIER_BLOCKLIST",
   "CLEAROTRON_INSTRUCTIONS_DIR",
   "CLEAROTRON_INVOKED_AS",
   "CLEAROTRON_JX_",

package/shared/os-advice.mjs

@@ -0,0 +1,91 @@
+// 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 COMMANDS WE TELL A READER TO TYPE, IN THE SHELL THEY ARE ACTUALLY IN.
+//
+// Three surfaces print a command for the reader to run: the port-in-use refusal, the client door's
+// version of the same, and the demo's "remove it later" line. All three printed POSIX commands
+// unconditionally — `ss`, `lsof`, `rm -rf` — and the demo is supported on native Windows, where none
+// of them exist. A reader who follows the instruction gets "not recognized as a cmdlet", which reads
+// as a broken product rather than as advice written for somebody else's machine.
+//
+// Reported from the owner's own Windows run, 2026-09-09.
+//
+// ONE PLACE, BECAUSE THREE COPIES OF A RULE DRIFT. The alternative was a ternary at each call site,
+// which is how the first one ends up saying `Remove-Item` while the second still says `rm -rf`.
+//
+// `platform` IS INJECTABLE ON EVERY FUNCTION, and that is the whole testability story: the population
+// this protects is the one that cannot run this suite to find out. An arm on a Linux runner has to be
+// able to ask what a Windows reader would be shown, or the Windows text is asserted by nobody.
+//
+// WHAT THIS DOES NOT DO: it does not detect a shell. A reader in Git Bash on Windows has POSIX
+// commands and will be shown PowerShell ones. That is the right way round — `process.platform` is a
+// fact and the shell is a guess, and being shown a command for the OS you are on is recoverable in a
+// way that being shown one for an OS you are not on is not.
+
+/** Is this the platform whose shell has none of the POSIX tools these messages used to name? */
+const isWindows = (platform) => platform === "win32";
+
+/**
+ * How to see which process holds a TCP port.
+ *
+ * The POSIX form keeps both spellings it always had: `ss` is on every modern Linux and `lsof` is the
+ * one a macOS reader has. The Windows form names the cmdlet AND how to turn its answer into a process,
+ * because `Get-NetTCPConnection` reports an owning PID and stops there — a reader given only that has
+ * been handed a number and no way to act on it.
+ */
+export function whatHoldsPort(port, { platform = process.platform } = {}) {
+  return isWindows(platform)
+    ? `Get-NetTCPConnection -LocalPort ${port} | Select-Object -ExpandProperty OwningProcess | `
+      + "ForEach-Object { Get-Process -Id $_ }"
+    : `ss -ltnp 'sport = :${port}'   (or: lsof -i :${port})`;
+}
+
+/** How to stop the process that turned up, once the reader has found it. */
+export const stopThatProcess = ({ platform = process.platform } = {}) =>
+  (isWindows(platform) ? "Stop-Process -Id <the PID above>" : "kill <the pid above>");
+
+/**
+ * How to remove one directory and everything under it.
+ *
+ * `-Recurse -Force` is the pair, and both are needed: without `-Recurse` PowerShell prompts for a
+ * non-empty directory, and a reader who is told to remove a directory and then asked to confirm each
+ * child has been given a command that does not do what the sentence said it would.
+ */
+export const removeDirectory = (dir, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `Remove-Item -Recurse -Force "${dir}"` : `rm -rf ${dir}`);
+
+/**
+ * Set one environment variable for the length of one command.
+ *
+ * `VAR=value cmd` is a POSIX shell construct with no PowerShell equivalent — there it is a statement of
+ * its own, so the pair has to be separated rather than juxtaposed. A reader who pastes the POSIX form
+ * into PowerShell is told the variable name is not a recognised cmdlet, which names the wrong half of
+ * the line as the problem.
+ */
+export const envPrefix = (name, value, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `$env:${name}="${value}"; ` : `${name}=${value} `);
+
+/**
+ * Move to a directory, then run what follows.
+ *
+ * `&&` IS THE PART THAT FAILS, not the path. Windows PowerShell 5.1 — still the default shell on a
+ * stock machine — has no `&&` operator at all, so `cd X && npx …` is a parse error there before the
+ * backslashes matter. `;` runs in both 5.1 and 7, and quoting the directory covers the spaces a
+ * Windows home path routinely carries.
+ *
+ * The POSIX form keeps `&&` deliberately: it is not a separator there, it is a guard, and running the
+ * command from the wrong directory because the `cd` failed is worse than not running it.
+ */
+export const chdirPrefix = (dir, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `cd "${dir}"; ` : `cd ${dir} && `);
+
+/**
+ * What keeps a background instance alive, named for the thing that actually does it.
+ *
+ * `null` where this platform has no such mechanism in the product, so a caller prints nothing rather
+ * than naming a service manager the reader does not have. Windows was told the background form was
+ * "managed by systemd", which is not on the machine and cannot be installed onto it.
+ */
+export const backgroundManager = ({ platform = process.platform } = {}) =>
+  (isWindows(platform) ? null : "systemd");

package/shared/reap-on-exit.mjs

@@ -36,8 +36,27 @@
 //
 // IDEMPOTENT, and unregistering is the caller's normal path: a child that exits on its own drops out,
 // so the reaper never signals a pid that has been recycled onto somebody else's process.
+//
+// ── WHY DIRECTORY REMOVAL LIVES IN THIS FILE AND NOT BESIDE IT ────────────────────────────────────
+//
+// A browser run's temp root can only be removed AFTER its process group is dead. Chrome's renderer,
+// GPU and zygote children keep writing the profile while they live, so a removal that runs first
+// races them and throws ENOTEMPTY — a race three of the call sites below already carry a comment
+// about, on their own success paths.
+//
+// Two separate exit handlers cannot express that ordering: Node runs `exit` listeners in
+// registration order, so the guarantee would depend on which module a caller happened to import
+// first. One handler doing both, in the order written here, is the whole reason `removeOnExit` is
+// not its own module.
+//
+// The removal is best-effort for the same reason the kill is: a handler that throws on the way out
+// of a crashing script replaces one problem with a worse one. `maxRetries` covers ENOTEMPTY, which
+// is the error the surviving-children race actually produces.
+
+import { rmSync } from "node:fs";
 
 const groups = new Set();
+const dirs = new Set();
 let installed = false;
 
 function reapAll() {
@@ -49,6 +68,11 @@ function reapAll() {
     try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ } }
   }
   groups.clear();
+  // ONLY NOW, with the groups signalled, is the temp root removable. See the note above.
+  for (const dir of dirs) {
+    try { rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); } catch { /* a stray temp root is not worth failing an exit over */ }
+  }
+  dirs.clear();
 }
 
 function install() {
@@ -77,7 +101,25 @@ export function reapOnExit(child) {
   return stop;
 }
 
+/**
+ * Remove `dir` when THIS process exits, by any route it can observe, and only after every watched
+ * process group has been signalled.
+ *
+ * @returns {() => void} stop watching, for a caller that removes the directory itself.
+ */
+export function removeOnExit(dir) {
+  if (typeof dir !== "string" || dir === "") return () => {};
+  dirs.add(dir);
+  install();
+  return () => dirs.delete(dir);
+}
+
 /** The pids currently watched. For arms — a reaper nobody can inspect is a reaper nobody can test. */
 export function watchedGroups() {
   return [...groups];
 }
+
+/** The directories currently watched, for the same reason. */
+export function watchedDirs() {
+  return [...dirs];
+}