clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/shared/connect-clients.mjs

@@ -398,15 +398,40 @@ export const leadRouteFor = (id) => {
  * invitation to paste it inside WSL, where it does not work. Somebody took the invitation from Claude
  * Code inside a distribution and got CONNECTION_CLOSED (measured 2026-09-16 on 0.3.2-beta.1).
  *
- * There is exactly ONE launcher per host shape today, and under WSL it is the Windows-side one, so this
- * step names the side it is for rather than offering both. Building the second launcher — the plain
- * `node` line for an assistant running inside the distribution — is its own piece of work; until it
- * exists, saying which side this one is for is the whole of what can honestly be said.
+ * AND NOW IT SAYS ONLY THAT THE INSTALL IS IN WSL, because the rows below it say the rest.
+ *
+ * While there was one launcher, this step carried which side it was for and that the other side could
+ * not use it. Both sides are now offered, each headed with the side it is for, and those two sentences
+ * turned false where they stand: the reader is told an assistant inside the distribution cannot connect,
+ * directly above the row that connects it. What is left is the clause that is still true and still
+ * needed — the rows name Linux paths and the reader has to know why. The rest is DELETED rather than
+ * reworded, because the headings already say it and nothing here is ours to write.
  */
-export const WSL_STEP = "This install runs inside WSL, and the command below starts the server in there for you. "
-  + "It is for an assistant running on the Windows side — Claude Desktop, or Claude Code in PowerShell. "
-  + "An assistant running inside this WSL terminal cannot use it: start the server from the WSL terminal "
-  + "yourself instead.";
+export const WSL_STEP = "This install runs inside WSL.";
+
+/**
+ * ONE ROW PER SIDE, where a launcher has two.
+ *
+ * `stdioConnectFor` answers a WSL install with both launchers under `variants`, headed in the product's
+ * own words. Each becomes a row of its own here, carrying its side's heading as the row's line and its
+ * side's command as the row's copy — so the reader sees which command is theirs before they press it,
+ * and does not paste the Windows one into a terminal already inside the distribution.
+ *
+ * The heading takes the row's line rather than a slot of its own: every surface that draws a step draws
+ * that line already — the page above the copy block, the terminal beside the number — so both sides get
+ * the headings from one author and neither needs new markup to show them.
+ *
+ * Anywhere else this is the identity. One launcher stays one row, with the line its author wrote.
+ */
+const splitSides = (step) => {
+  const variants = step.copy?.stdio?.variants;
+  if (!variants) return [step];
+  return variants.map((v) => ({
+    ...step,
+    text: v.heading,
+    copy: { ...step.copy, text: v.text, stdio: { ...step.copy.stdio, text: v.text, variants: null } },
+  }));
+};
 
 export function whatItNeeds(client, have = {}, route = client?.lead) {
   if (!client) return null;
@@ -494,10 +519,13 @@ export function whatItNeeds(client, have = {}, route = client?.lead) {
     // ON WSL, "THIS COMPUTER" IS THE LINUX INSIDE WINDOWS. The line names WSL paths, so it runs in the WSL
     // terminal where Clearotron is installed. Pasted into PowerShell it fails, and an assistant running on
     // Windows itself could not start a program at a Linux path anyway.
-    if (have.wsl) steps.unshift({ text: WSL_STEP });
-    const first = steps.find((s) => s.copy)?.copy;
+    // AND A LAUNCHER WITH TWO SIDES BECOMES TWO ROWS, under the step that says this install is in WSL.
+    const rows = steps.flatMap(splitSides);
+    if (have.wsl) rows.unshift({ text: WSL_STEP });
+    // The Windows-side row leads, so `command` and `stdio` answer what they have always answered.
+    const first = rows.find((s) => s.copy)?.copy;
     // `command` and `stdio` ride for the terminal, which prints a disk offer's copy by its shape.
-    return { client, served: true, route, steps, launch: client.launch ?? null, enables: null, ...evidence,
+    return { client, served: true, route, steps: rows, launch: client.launch ?? null, enables: null, ...evidence,
       command: first?.text ?? null, stdio: first?.stdio ?? null, address: null, key: null,
       note: "Nothing to sign up for and nothing to open up — this assistant runs the software itself, from the copy already on this machine." };
   }

package/shared/deployment-box.mjs

@@ -16,10 +16,15 @@
 // of the same allowlist agree on the day they are written and drift afterwards; that is the defect
 // was filed about one field over, and the fix there was the same — import the function, never
 // re-derive the answer.
-export const DEPLOYMENT_BOXES = ["prod", "test"];
+// `preprod` JOINED 2026-09-17. It is a packaged install like production, on its own account, which takes
+// every published version before production does. Until it could name itself it ran with the variable
+// UNSET — and an unset box does not fail loudly: `live-surface-check` SKIPS its expected-units check
+// when the box is null, so the one install that most wants that check was the one not getting it.
+// Setting `prod` instead would have made the box lie about which box it is.
+export const DEPLOYMENT_BOXES = ["prod", "preprod", "test"];
 
 /**
- * @returns {"prod"|"test"|null} the self-declared box, or null when unset or unrecognised.
+ * @returns {"prod"|"preprod"|"test"|null} the self-declared box, or null when unset or unrecognised.
  *
  * Read at CALL time, deliberately. `shared/brand.mjs` builds its value at module scope and that is
  * exactly why a rename reached the report and not the portal — portal-service is outside

package/shared/driver-dir.mjs

@@ -35,7 +35,7 @@
 // its own population needs an exception list — which would rebuild this issue's defect inside its fix:
 //
 //   · `driver/stage-freshness.mjs` creates a CHILD, `join(runDir, "_driver", STAMP_DIR)`.
-//   · `driver/pipeline.mjs:15945 shadowDir` passes a shadow dispatch sandbox under `_experiments/`, not a run
+//   · `driver/pipeline.mjs shadowDir` passes a shadow dispatch sandbox under `_experiments/`, not a run
 //     directory. It is a run-dir-SHAPED base, which is why the parameter is `base` and not `runDir`.
 //
 // ── WHAT THIS DELIBERATELY DOES NOT DO ────────────────────────────────────────────────────────────

package/shared/env-aliases.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
 // env-aliases.mjs — ONE SPELLING, and the settings that no longer exist at all.
 //
-// A variable name must mean something to someone who has never read this code. `PRELIM` names nothing
+// A variable name must mean something to someone who has never read this code. `CLEARANCE` names nothing
 // to anyone — it is the internal codename of the first product this engine shipped — so the names an
 // installer types are `CLEAROTRON_*`. Vendor keys are deliberately untouched: `SIGNA_API_KEY` already
 // says who you bought it from.

package/shared/identifier-scan.mjs

@@ -17,6 +17,7 @@
 // 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.
+import { createHash } from "node:crypto";
 
 // ── the platform and public-register exemption ────────────────────────────────────────────────────
 //
@@ -72,6 +73,26 @@ export const ALLOWED_TOKEN_CONTEXT =
 
 export const ALLOWED_LINE_CONTEXT = /owner-bound|watchlist owner/i;
 
+// ── THE CLOUD, AS A BILLING ROUTE ──────────────────────────────────────────────────────────────────
+//
+// Claude can be paid for through a cloud account, and one of the three clouds is Azure. The roster
+// retires the same word as a client, so every sentence about paying through that cloud was refused as a
+// retired identity: 67 of the 99 hits over the tree on 2026-09-18, and 11 lines of a release's squash
+// message.
+//
+// EXACTLY AS WIDE AS THE EVIDENCE, AND NO WIDER. Only the names the product itself ships for that route
+// are exempt: the cloud's name, its Foundry service, and the three clouds named as a list. Case-sensitive,
+// because that is how the product spells them. The bare word is never exempt, in any casing, and a
+// sentence that used it as shorthand for the cloud was reworded to say Azure instead.
+//
+// AND NOT IN CAPTURED DATA. A frozen demo run and a captured register fixture hold third parties' own
+// text: a course title that happens to name the cloud is not a billing route, so there the rule does not
+// apply and the hit is reported as it always was.
+export const CLOUD_ROUTE_CONTEXT = /\bMicrosoft Azure\b|\bMicrosoft Foundry\b|\bGoogle(?: Cloud)?,\s+Microsoft(?: Azure)?\s+or\b/;
+
+/** A frozen demo run, anywhere under `demo/<product>/run/`: what the engine read, captured whole. */
+const FROZEN_RUN_RE = /(?:^|\/)demo\/[^/]+\/run\//;
+
 /**
  * Kept as the union so nothing that merely ASKS "is this line exempt at all" has to learn the split.
  * Callers deciding whether to REPORT a hit must use the two above — this one cannot tell you which
@@ -155,20 +176,27 @@ export function matchSpans(name, line, suffixable) {
  *
  * Takes the RAW line and does its own unescaping, so no caller can forget that step.
  */
-export function reportableOnLine(name, rawLine, suffixable) {
+export function reportableOnLine(name, rawLine, suffixable, { cloudRoute = true } = {}) {
   if (ALLOWED_LINE_CONTEXT.test(rawLine)) return false;
   const text = unescapeBoundaries(rawLine);
-  return matchSpans(name, text, suffixable).some((sp) => !tokenExemptionCovers(text, sp));
+  return matchSpans(name, text, suffixable).some((sp) => !tokenExemptionCovers(text, sp, { cloudRoute }));
 }
 
-function tokenExemptionCovers(line, span) {
-  for (const m of String(line).matchAll(new RegExp(ALLOWED_TOKEN_CONTEXT.source, "gi"))) {
-    const s = m.index, e = m.index + m[0].length;
-    if (span.start < e && s < span.end) return true;   // overlap, in either direction
+function tokenExemptionCovers(line, span, { cloudRoute = true } = {}) {
+  const contexts = [new RegExp(ALLOWED_TOKEN_CONTEXT.source, "gi")];
+  if (cloudRoute) contexts.push(new RegExp(CLOUD_ROUTE_CONTEXT.source, "g"));
+  for (const rx of contexts) {
+    for (const m of String(line).matchAll(rx)) {
+      const s = m.index, e = m.index + m[0].length;
+      if (span.start < e && s < span.end) return true;   // overlap, in either direction
+    }
   }
   return false;
 }
 
+/** Whether the cloud-route exemption applies in this file: everywhere but captured third-party data. */
+export const cloudRouteApplies = (file) => !isCapturedRegisterData(file) && !FROZEN_RUN_RE.test(String(file ?? ""));
+
 // ── CAPTURED PUBLIC-REGISTER DATA ─────────────────────────────────────────────────────────
 //
 // `providers/*/test/fixtures/` holds vendor responses captured live from public trademark registers.
@@ -208,6 +236,32 @@ export const CAPTURED_DATA_GUIDANCE =
   + "`node scripts/check-capture.mjs <file>` before writing; or (b) a genuine identifier of ours — remove "
   + "it. Do NOT exempt the path: captured data is the one place a real identifier could hide unseen.";
 
+// ── A PUBLISHED DICTIONARY, PINNED TO ITS BYTES ─────────────────────────────────────────────
+//
+// The roster retires ordinary English words, and a dictionary is every ordinary English word, so the
+// two collide by construction and, like captured register data, the collision arrives on a tree
+// nobody touched: the private roster gains an entry and the word list goes red. Unlike captured data,
+// nothing of ours can be in it. It is a published third-party list (the file's header names it and its
+// licence) that no client, matter or run ever wrote to.
+//
+// SO THE EXEMPTION IS FOR THESE BYTES, NOT THIS PATH. Each entry pins the file's SHA-256 as it was
+// vetted. Change one line, a name slipped in among the words, and the hash no longer matches: the file
+// is scanned in full again like any other, and the pin moves only in a commit that says it re-vetted.
+// A name hidden in a dictionary is therefore still a finding, and a name anywhere else never was
+// exempt.
+export const PINNED_DICTIONARIES = Object.freeze({
+  "driver/wordlists/en.txt": Object.freeze({
+    sha256: "8021ad10f94da2a549f60db93fcf761156458fd682e1095e81f93db6843fb636",
+    what: "SCOWL size 50, American: the one-letter neighbourhood filter's ordinary-word list",
+  }),
+});
+
+/** Is this file a pinned dictionary whose bytes are exactly the ones that were vetted? */
+export function isPinnedDictionary(file, text) {
+  const pin = PINNED_DICTIONARIES[String(file ?? "")];
+  return Boolean(pin) && createHash("sha256").update(String(text)).digest("hex") === pin.sha256;
+}
+
 /**
  * Sweep a corpus for retired identities.
  *
@@ -227,6 +281,7 @@ export function scanCorpus(files, readFn, { retired, suffixable, vetted = () =>
   for (const f of files) {
     const t = readFn(f);
     if (!t) continue;
+    if (isPinnedDictionary(f, t)) continue;
     // In captured register data the hit is reported by ENTRY NUMBER, never by value. The
     // ordinary format prints the retired name and its twin, which is right where the fix is "delete
     // this" — but a fixture collision is expected to fire on a tree nobody changed, and printing the
@@ -239,7 +294,7 @@ export function scanCorpus(files, readFn, { retired, suffixable, vetted = () =>
         entry += 1;
         // A LINE-scoped exemption skips the line; a TOKEN-scoped one must OVERLAP the match it excuses.
         // Both live in reportableOnLine, so the declaration test cannot answer this differently.
-        if (!reportableOnLine(name, line, suffixable)) continue;
+        if (!reportableOnLine(name, line, suffixable, { cloudRoute: cloudRouteApplies(f) })) continue;
         if (vetted(f, name)) continue;
         hits.push(captured
           ? `${f}:${i + 1}: match table entry #${entry} of ${retired.length} (sentinels first, then the roster) `
@@ -302,8 +357,8 @@ const ADDRESS = /([A-Za-z0-9._%+-]+)@(?:cordillera\.(?:ch|test)|clearotron\.ai)\
 const INTERNAL_MARKER = /\bINTERNAL[ -]ONLY\b/;
 const INTERNAL_PHRASE = /\bfor internal use only\b/i;
 
-// THE SECOND STAMPED FORM, and is why it exists. `driver/skills/prelim-search/worked-examples.md`
-// opened with `INTERNAL — Gold-standard worked examples for prelim-search SYNTHESIS.` and shipped: the
+// THE SECOND STAMPED FORM, and is why it exists. `driver/skills/clearance-search/worked-examples.md`
+// opened with `INTERNAL — Gold-standard worked examples for clearance-search SYNTHESIS.` and shipped: the
 // marker above requires the word ONLY, and a document stamped `INTERNAL —` carries the identical
 // classification without it.
 //
@@ -361,6 +416,7 @@ export function scanOperatorIdentity(files, readFn, { withheld = () => false } =
   for (const f of files) {
     const t = readFn(f);
     if (!t) continue;
+    if (isPinnedDictionary(f, t)) continue;
     // A WITHHELD PATH DOES NOT SHIP, and pattern 4 is about what a shipped surface says to its reader.
     // The withheld design tree holds twenty-one hits of exactly this shape and every one is correct in
     // place: working notes, withheld wholesale by the list in shared/withheld-paths.mjs, and rewriting

package/shared/identifier-sentinels.mjs

@@ -32,3 +32,25 @@ export const SENTINELS = [
 // and `Brindlow-Reach`. One row carries it so the option itself is exercised rather than merely
 // declared — an unexercised option is a setting nobody has watched work.
 export const SUFFIXABLE = new Set(["Brindlow"]);
+
+/**
+ * WHICH TABLE THE SWEEP WAS ARMED WITH, said out loud so a workflow can require it.
+ *
+ * The public tree can only ever run this sweep in sentinel mode — the real roster lives outside the
+ * repository by design, and the arm that sweeps here is wired to SENTINELS by construction. That is
+ * fine, and it is exactly why the mode has to be stated: a sweep with an empty table returns the same
+ * clean zero as a sweep that worked, so "it ran, and here is which table it ran against" is the only
+ * form of the claim a reader can act on.
+ *
+ * It is printed by the arm that actually sweeps the corpus, never at import. A marker that appeared
+ * merely because a module was loaded would survive the arm being deleted, which is the one thing it
+ * exists to catch — the guard stopping and every run staying green.
+ */
+export const SENTINEL_MODE_MARKER = "[repo-guard] blocklist mode=sentinel";
+
+/**
+ * The line the sweep prints when it read a REAL roster instead. That roster is private and never
+ * reaches this repository's runners by design, so on a public run the line does not mean a stronger
+ * check: it means the roster was loaded into a public log. The workflow refuses it.
+ */
+export const TABLE_MODE_MARKER = "[repo-guard] blocklist mode=table";

package/shared/names-in-force.mjs

@@ -3,7 +3,7 @@
 // names-in-force.mjs — GENERATED by scripts/mint-names-in-force.mjs. Do not edit by hand.
 //
 // Every `CLEAROTRON_*` name this build reads. It exists so the retired-spelling check can name the
-// replacement for an old `PRELIM_*` line rather than only saying the old one is dead — see
+// replacement for an old `CLEARANCE_*` line rather than only saying the old one is dead — see
 // shared/env-aliases.mjs. Re-mint with:
 //
 //   node scripts/mint-names-in-force.mjs
@@ -23,7 +23,6 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_AI",
   "CLEAROTRON_AI_BILLING",
   "CLEAROTRON_AI_PATH",
-  "CLEAROTRON_AZURE_MODEL",
   "CLEAROTRON_BAND_RESPONSE_CHARS",
   "CLEAROTRON_BAND_RUN_DIR",
   "CLEAROTRON_BAND_TRUTH_GATE",
@@ -41,7 +40,9 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_COMMONLAW_SPLIT",
   "CLEAROTRON_COUNT_FIRST",
   "CLEAROTRON_CUSTOMERS_DIR",
+  "CLEAROTRON_CUT_PR",
   "CLEAROTRON_CUT_REF",
+  "CLEAROTRON_CUT_REQUESTED",
   "CLEAROTRON_DATABASE",
   "CLEAROTRON_DEFAULT_AGENT",
   "CLEAROTRON_DELIVERY",
@@ -54,6 +55,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_E2E_EVIDENCE_DIR",
   "CLEAROTRON_E2E_EXPECT_DEMO_ROSTER",
   "CLEAROTRON_EDGE_ORIGIN",
+  "CLEAROTRON_ENGINES_DIR",
   "CLEAROTRON_ENGINE_CWD",
   "CLEAROTRON_ENGINE_MAX_BUFFER",
   "CLEAROTRON_ENUMERATE_CEILING",