clearotron 0.2.2 → 0.2.4

package/bin/onboard.mjs

@@ -64,11 +64,16 @@ import { stdin as input, stdout as output } from "node:process";
 import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";   // read the process table here; moved that to shared/process-table.mjs
 import { homedir, userInfo } from "node:os";
 import { invocationPrefix } from "../shared/invocation.mjs";   // — one rule for how the reader invokes us
+import { nodeFloorVerdict } from "../shared/node-floor.mjs";   // — the floor is package.json engines, not a constant here
 import { invocationForm } from "../shared/invocation.mjs";   // — and WHY that form
 import { standFrom } from "../shared/invocation.mjs";   // is this tree one npm replaces?
 import { installShim } from "../shared/verb-shim.mjs";   // — the verb goes on PATH
 import { styleFor, banner } from "../shared/tty-style.mjs";   // — weight where the meaning is
-import { bracketAsciiCells } from "../shared/brand.mjs";      // F18 — the mark, from the geometry the SVG already uses
+import { bracketAsciiCells, BRAND } from "../shared/brand.mjs";      // F18 — the mark, from the geometry the SVG already uses
+// ONE CLASSIFIER, shared with `bin/start.mjs`. The wizard asks the question; the launcher enforces the
+// answer. Two copies of "what does this domain admit" is a wizard that consents to one rule and a
+// launcher that builds another.
+import { classifyStaffDomain, domainOfEmail, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
 import { join, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { delimiter } from "node:path";
@@ -121,7 +126,6 @@ const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed
 // command is applying. Writes stay on ENV_PATH: a writer that followed the file backwards would keep an
 // install in the directory npm replaces forever.
 const READ_ENV_PATH = () => activeEnvPath({ repoRoot: REPO });
-const NODE_FLOOR = 22;
 
 const argv = process.argv.slice(2);
 const has = (n) => argv.includes(n);
@@ -587,30 +591,194 @@ export const AMBIENT_KEYS = [
 // ── helpers ──────────────────────────────────────────────────────────────────────────────────────────
 const present = (v) => typeof v === "string" && v.trim() !== "";
 
+/**
+ * Ask who signs in, and take a real yes for the access rule that address implies.
+ *
+ * ── WHY THIS QUESTION EXISTS AT ALL ─────────────────────────────────────────────────────────────────
+ *
+ * Setup never asked for an address. `clearotron start` therefore took one from `--user`, from
+ * `PORTAL_LOCAL_USER`, or from the local account as `<account>@localhost` — and derived a STAFF RULE
+ * from everything after its `@`. On the local-account default that rule is `localhost`: one machine,
+ * one identity, nothing granted to anyone. Given a real address it is that address's whole domain, and
+ * the settings page then reports it back as "Anyone at <domain> — a rule, not a person".
+ *
+ * An outside install reached exactly that state. Nobody typed the address into this wizard, because
+ * this wizard had no prompt for it; an assistant filled one into the environment file on the operator's
+ * behalf, and the install granted a documentation domain. They read their own settings page and
+ * reported it as a back door. They were right to: a grant to a group had been made, by nobody.
+ *
+ * So the address is asked for here, where a person is definitionally present, and the grant it implies
+ * is shown in the words the settings page uses BEFORE it is written. `start` no longer guesses: it
+ * refuses a rule wider than one machine unless `PORTAL_STAFF_DOMAINS` says so in writing, which is what
+ * a yes here writes.
+ *
+ * THE DEFAULT IS THE LOCAL ACCOUNT AND NOTHING ELSE — not the git author, not the hostname, not a shell
+ * variable. An identity that becomes an access rule comes from the person, or from the one source that
+ * cannot name a second person.
+ *
+ * `io` IS INJECTED for the reason `offerUsptoSync`'s is: the branch that matters is the one where a
+ * reader pressed Enter at the grant question and NOTHING must be granted, and closed over a terminal
+ * that branch is asserted nowhere. Returns the `.env` keys to write and nothing else.
+ */
+export async function askSignIn(io, { localAccount = "user", staffLabel = "Staff", envPath = "" } = {}) {
+  const { askValue, confirm, say = () => {}, ok = () => {}, info = () => {},
+          warn = () => {}, problem = () => {} } = io;
+  const localDefault = `${localAccount}@localhost`;
+  prose("The portal admits one address on this install, and that address is also what decides who is an",
+        "administrator. Enter accepts the local-account form, which is this machine and nobody else.");
+  for (;;) {
+    const typed = String(await askValue("Sign-in address:", { def: localDefault })).trim().toLowerCase();
+    if (!typed.includes("@") || typed.indexOf("@") !== typed.lastIndexOf("@")) {
+      problem(`"${typed}" is not a single email address. The portal refuses a multi-@ identity outright, `
+        + "so this would sign in and then be denied at the door.");
+      continue;
+    }
+    const domain = domainOfEmail(typed);
+    const verdict = classifyStaffDomain(domain);
+    if (verdict === "public" || verdict === "reserved") {
+      // The classifier's own sentence, never a second copy: `clearotron start` prints these same words
+      // when it meets the same domain, and two wordings of one refusal is how a reader comes to believe
+      // they have met two different problems.
+      problem(staffDomainRefusal(domain));
+      continue;
+    }
+    if (verdict === "narrow") {
+      ok(`${typed} — this machine only. No domain rule is written, and nobody else is granted anything.`);
+      return { PORTAL_LOCAL_USER: typed };
+    }
+    // `wide`: a real domain, so the grant is a grant. Stated first, in the settings page's own words,
+    // and Enter is NOT a yes — the default is no, because this is the one answer in the wizard that
+    // admits people the reader has never met.
+    say("");
+    warn(`${typed} makes this a rule about ${domain}, not about you.`);
+    say(`    ${staffGrantSentence(domain, { staffLabel })}`);
+    say("");
+    say(`  Everyone at ${domain} who gets past this install's sign-in door would see every brand owner`);
+    say("  on it — every clearance, every report, every configuration. On a laptop that is only you,");
+    say("  because only one address can sign in. Behind a company login it is the whole domain.");
+    say("");
+    if (await confirm(`Grant ${domain} that, and write it down as PORTAL_STAFF_DOMAINS?`, false))
+      return { PORTAL_LOCAL_USER: typed, PORTAL_STAFF_DOMAINS: domain };
+    info(`nothing granted${envPath ? `, and nothing written to ${envPath}` : ""}. ${typed} would sign in `
+      + "and every page would refuse it, because signing in is not being enrolled — so choose the "
+      + "local-account form, or answer yes above.");
+  }
+}
+
 /**
  * An engine binary, resolved the way the engine resolves it — and the trap that resolution carries.
  *
  * Was `resolveClaudeBin`. The body never had anything claude-specific in it; the NAME was the last place
  * this file still assumed one engine, and a name that lies is how the second adapter stayed invisible.
  */
-export function resolveEngineBin(bin) {
+export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindowsDrive = null } = {}) {
+  // The predicate, not just the pattern, because /mnt/c cannot be created on a Linux runner without
+  // root — so an arm that could only supply a PATH could never drive the skip, and the branch would
+  // ship asserted by nobody. `ON_A_WINDOWS_DRIVE` is held to real paths by its own arm.
+  const onDrive = onWindowsDrive ?? ((x) => ON_A_WINDOWS_DRIVE.test(x));
   // driver/engine/anthropic-agent.mjs — `CLEAROTRON_CLAUDE_PATH || "claude"`; openai-agent.mjs — the same
   // shape on `CLEAROTRON_CODEX_PATH || "codex"`. A RELATIVE path is the trap for BOTH: stage subprocesses are
   // spawned with cwd set to the RUN DIRECTORY (driver/engine/common.mjs resolveSpawnCwd, shared by the
   // two adapters), so a relative binary resolves against a directory that did not exist at setup time.
+  const underWsl = wsl ?? isWsl({ env });
   if (bin.includes("/")) {
     const abs = resolve(bin);
-    if (!isAbsolute(bin)) return { path: abs, executable: isExec(abs), relative: true };
-    return { path: abs, executable: isExec(abs), relative: false };
+    // A PATH SOMEBODY TYPED IS NOT OVERRULED, only reported. The reader stated this one, and silently
+    // resolving somewhere else would be the launcher moving a door off a port that was asked for.
+    return { path: abs, executable: isExec(abs), relative: !isAbsolute(bin), windowsShim: underWsl && onDrive(abs), skipped: [] };
   }
-  for (const dir of (process.env.PATH || "").split(delimiter).filter(Boolean)) {
+  // ── UNDER WSL, THE WINDOWS PATH IS APPENDED TO THIS ONE ────────────────────────────────────────
+  //
+  // So `claude` on a fresh WSL2 Ubuntu resolves to /mnt/c/…/claude — the WINDOWS shim — before any
+  // Linux install is reached, and it is executable by every test this makes. It then fails the proof
+  // turn as "not signed in", because the credential it is looking for is the Linux one, and a reader
+  // is sent to fix a sign-in that was never the problem. Reported from a real WSL2 attempt.
+  //
+  // SKIPPED, AND NAMED. Passing over a candidate silently would leave the reader with "no binary
+  // found" on a machine where `which claude` prints one, so the skips travel back for the caller to
+  // say out loud. A missing Linux install then reports as missing, which is the true answer.
+  const skipped = [];
+  for (const dir of (env.PATH || "").split(delimiter).filter(Boolean)) {
     const p = join(dir, bin);
-    if (isExec(p)) return { path: p, executable: true, relative: false };
+    if (!isExec(p)) continue;
+    if (underWsl && onDrive(p)) { skipped.push(p); continue; }
+    return { path: p, executable: true, relative: false, windowsShim: false, skipped };
   }
-  return { path: null, executable: false, relative: false };
+  return { path: null, executable: false, relative: false, windowsShim: false, skipped };
+}
+
+/** A path on a Windows drive as WSL mounts it. */
+export const ON_A_WINDOWS_DRIVE = /^\/mnt\/[a-z]\//i;
+
+/**
+ * Whether this is a Linux running under Windows.
+ *
+ * BOTH SIGNALS INJECTABLE, for the reason `platformEngineRefusal` gives: the readers this protects
+ * are the ones who cannot run this suite to find out, so a Linux runner has to be able to drive both
+ * answers rather than read the source and agree with it.
+ *
+ * A READ THAT FAILS ANSWERS "NOT WSL", and that is the direction that changes nothing: it leaves the
+ * resolution exactly as it was before this existed. Claiming WSL on a could-not-read would start
+ * refusing candidates under /mnt on an ordinary Linux box with an ordinary mount.
+ */
+export function isWsl({ env = process.env, procVersion = null } = {}) {
+  if (String(env.WSL_DISTRO_NAME ?? "").trim()) return true;
+  if (String(env.WSL_INTEROP ?? "").trim()) return true;
+  const v = procVersion ?? (() => { try { return readFileSync("/proc/version", "utf8"); } catch { return ""; } })();
+  return /microsoft|wsl/i.test(v);
+}
+
+/**
+ * What to say about candidates passed over because they sit on a Windows drive — or `null` when none
+ * were. Plural because a reader can have both a shim and a wrapper on PATH.
+ */
+export function windowsShimNote(skipped, bin) {
+  if (!skipped?.length) return null;
+  return `ignored ${skipped.length === 1 ? "a `" + bin + "` on a Windows drive" : skipped.length + " `" + bin + "` binaries on Windows drives"} `
+    + `(${skipped.join(", ")}): WSL appends the Windows PATH to this one, and a Windows build cannot run a `
+    + `stage here — it fails the proof turn as "not signed in" while holding a credential this side never `
+    + `wrote. Install it inside the Linux distribution instead.`;
 }
 const isExec = (p) => { try { accessSync(p, constants.X_OK); return statSync(p).isFile(); } catch { return false; } };
 
+/**
+ * What doctor says about the engine on a platform the run door refuses outright, or `null` where the
+ * ordinary binary checks apply.
+ *
+ * `platform` IS INJECTABLE, and for the reason `preflightEngineBinary` gives at its own refusal: 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 is shown, or the Windows text is asserted by nobody —
+ * and reading `process.platform` inside the caller would make that arm read source instead of driving
+ * the answer.
+ */
+export function platformEngineRefusal({ platform = process.platform } = {}) {
+  if (platform !== "win32") return null;
+  return "this engine does not run on native Windows — stage subprocesses are spawned with POSIX path "
+    + "and process semantics, so the run door refuses before it reads PATH. Run it under WSL2, or in "
+    + "the devcontainer. The demo works here as it is: it replays finished reports and needs no engine.";
+}
+
+/**
+ * How to leave demo mode, which is not the same instruction everywhere.
+ *
+ * On the platform the run door refuses, the standard advice is a loop: install a CLI the reader may
+ * already have, then restart a service — neither of which can change the answer, because the refusal
+ * is about the platform rather than the program. Naming WSL2 is the only instruction that ends it.
+ */
+export function leaveDemoAdvice(engSpec, { platform = process.platform } = {}) {
+  if (platform === "win32") {
+    return [`To leave demo on Windows: run the product under WSL2, or in the devcontainer. Installing `
+      + `${engSpec.vendor}'s CLI natively will not change this — the run door refuses on the platform, `
+      + "not on the program."];
+  }
+  return [
+    `To leave demo: install ${engSpec.vendor}'s CLI (\`${engSpec.fallback}\`)`
+      + `${engSpec.install ? ` with \`${engSpec.install}\`` : ""}, then ${engSpec.signIn}.`,
+    "Restart any running engine service afterwards so it re-reads its PATH: the portal reports what the "
+      + "engine saw when it last started, and it will not notice a new install until then.",
+  ];
+}
+
 /**
  * The engine menu, built from the driver's registry so the wizard cannot offer an adapter that does not
  * exist — or hide one that does. Same guarantee the register-provider list has.
@@ -998,9 +1166,9 @@ export async function runCheck() {
   }
 
   say("\n  Node");
-  const major = Number(process.versions.node.split(".")[0]);
-  if (major >= NODE_FLOOR) ok(`node ${process.versions.node}`);
-  else problem(`node ${process.versions.node} — this engine needs >= ${NODE_FLOOR} (node:sqlite and TS type-stripping are load-bearing)`);
+  const nodeV = nodeFloorVerdict();
+  if (nodeV.ok) ok(`node ${nodeV.current}`);
+  else problem(`node ${nodeV.current} — this engine needs ${nodeV.required} or newer; node:sqlite is not a built-in module before then`);
 
   // Read the file up here rather than at the `.env` heading below: the engine section is the first that
   // needs `effective()`, and which ENGINE is configured decides which binary variable to check. Reading
@@ -1123,7 +1291,28 @@ export async function runCheck() {
     const binSet = !!binEff;
     const binSetting = binEff?.v || engSpec.fallback;
     const bin = resolveEngineBin(binSetting);
-    if (bin.executable && !bin.relative) ok(`${bin.path}`);
+    // ── NATIVE WINDOWS IS ANSWERED HERE, BEFORE ANY PATH IS RESOLVED OR REPORTED ──────────────────
+    //
+    // `resolveEngineBin` tests a candidate with `accessSync(X_OK)` and `isFile()`. Windows has no
+    // execute bit, so X_OK is satisfied by any file that exists — and an npm global install writes
+    // BOTH `claude`, an extensionless shell script for Git Bash, and `claude.cmd`. The POSIX test
+    // passes on the shell script, so this line reported the engine FOUND at a path CreateProcess
+    // cannot start, and the probe then failed with `spawn claude ENOENT`. Reported from a real
+    // Windows run, 2026-09-09.
+    //
+    // RESOLVING `claude.cmd` INSTEAD WOULD MOVE THE CONTRADICTION, NOT REMOVE IT.
+    // `preflightEngineBinary` refuses native Windows by name, and the run door calls it
+    // unconditionally — so a clearance cannot run here whatever this line finds. Making the probe
+    // succeed would produce a doctor that says ready, a probe that passes, and a run that refuses
+    // anyway: the same disagreement one step later, and more convincing for having spawned something.
+    //
+    // So doctor says what the run door says. That is the property — the two agree — and the reader
+    // gets one refusal they can act on instead of a found-then-failed sequence that sends them
+    // looking for a PATH problem they do not have. The demo is unaffected: it replays finished runs
+    // and needs no engine, which is why four reports published on that same Windows box.
+    const platformRefusal = platformEngineRefusal();
+    if (platformRefusal) problem(platformRefusal);
+    else if (bin.executable && !bin.relative) ok(`${bin.path}`);
     // The FACT only. It used to carry "install it for a real run (`npm run example` needs no engine)",
     // which is the absence framing was filed about — and it now says half of what the MODE line
     // below says, in worse words. One statement of a state, in the place that states states.
@@ -1134,6 +1323,15 @@ export async function runCheck() {
     else if (bin.relative) problem(`${engSpec.env}="${binSetting}" is RELATIVE — stage subprocesses run with cwd set to the run directory, so it will not resolve there. Use an absolute path (${bin.path} from here)`);
     else if (!bin.path) problem(`${engSpec.env}="${binSetting}" resolves to nothing on PATH`);
     else problem(`${engSpec.env}="${binSetting}" → ${bin.path} is not an executable file`);
+    // SAID AFTER THE CHAIN ABOVE, AND OUTSIDE IT. This block is one if/else-if ladder, so a statement
+    // placed between two of its clauses re-parents every clause below onto the new `if` — measured:
+    // it made doctor report an executable mock binary as "not an executable file", because the ladder's
+    // tail became the else of THIS condition. Said whether or not a binary was found: under WSL a
+    // Windows build on the appended PATH is passed over, and if a Linux one was found the reader still
+    // needs to know which of the two they have, while if none was, "no binary" over a machine whose own
+    // `which` prints one is a refusal nobody can act on.
+    const shimNote = windowsShimNote(bin.skipped, engSpec.fallback);
+    if (shimNote) info(shimNote);
 
     // ── — WHICH MODE THIS INSTALL IS IN, said as a mode rather than as a list of absences ──────
     //
@@ -1164,12 +1362,60 @@ export async function runCheck() {
     if (installMode === ENGINE_MODES.DEMO) {
       info("MODE: demo — everything works except starting a NEW search. The example report, its audit trail "
         + "and the MCP connection are live right now; `npm run example` needs no engine.");
-      info(`To leave demo: install ${engSpec.vendor}'s CLI (\`${engSpec.fallback}\`), then ${engSpec.signIn}.`);
+      // NAMES THE COMMAND, AND THE RESTART. The settings page says both now, and a doctor that named
+      // the program but not how to install it — or that left out the restart, which is what actually
+      // unsticks a reader who has just installed it — would be the third opinion this issue exists to
+      // remove. Same words on all three surfaces, taken from the same table.
+      // THE WAY OUT IS NOT THE SAME ON EVERY PLATFORM, and on the one where it differs the standard
+      // advice is a loop: a Windows reader is told to install a CLI they may already have, and then to
+      // restart a service — neither of which can change the answer, because the refusal is about the
+      // platform rather than the binary. Naming WSL2 is the only instruction that ends this state.
+      for (const line of leaveDemoAdvice(engSpec)) info(line);
     } else {
       info("The engine program is installed. Whether it is signed in cannot be read from disk: run "
         + "clearotron doctor --probe-engine to find out.");
     }
 
+    // AND WHETHER THE ENGINE AGREES, which is a different question from the one above and the reason an
+    // outside user gave up on this product. This command reads its OWN environment; the portal's New
+    // clearance screen reads what the engine recorded when it last started. Both were right and they
+    // said opposite things, so a reader who checked the confident-looking one first was told the engine
+    // was fine while no search would start. Reported here in the same words the configuration page uses,
+    // because a doctor that cannot see a contradiction the product ships with is the wrong doctor.
+    try {
+      const { readFlagSnapshot, postureDisagreement } = await import("../driver/flag-snapshot.mjs");
+      // THE READ-SIDE ACCESSOR, because this is a read: `config.poolRoot` throws on a box with no pool
+      // configured, and `readFlagSnapshot(null)` already answers "no capture" for exactly that case.
+      const snap = readFlagSnapshot(config.poolRootOrNull);
+      const rows = snap
+        ? postureDisagreement(snap, { flags: {}, engine: engineInventory(invEnv) })
+        : null;
+      // NULL IS NOT AGREEMENT and neither is an empty pool — a box with no capture has nothing to
+      // disagree with, and saying so beats printing a clean bill nobody measured.
+      const clash = (rows ?? []).find((r) => r.what === "engine program");
+      if (clash) {
+        problem(`The engine that last ran and this machine disagree about the engine program: the last run `
+          + `recorded it as ${clash.capture}, this machine reads it as ${clash.live}. A NEW search will `
+          + `refuse while that is true. Restart the engine service so it re-reads its PATH, or install the `
+          + `CLI where the service can see it.`);
+      }
+    } catch (e) {
+      // WHAT ACTUALLY REACHES THIS CATCH, established by driving it rather than by reading it.
+      //
+      // Not a box with no pool: `poolRootOrNull` answers null and `readFlagSnapshot(null)` answers null,
+      // neither throwing. And NOT an unreadable capture either — `readFlagSnapshot` has its own try and
+      // returns null for a corrupt file, so a damaged capture is already indistinguishable from an absent
+      // one by the time this code sees it. That is worth knowing and is not this change's to fix.
+      //
+      // So this catch covers an import that has broken or an unexpected throw out of the comparison —
+      // the check having stopped running. A doctor silent about its own failure is the defect the rest of
+      // this change is about, an absence rendered as a clean bill, so it says so. A caution rather than a
+      // problem: the engine may be perfectly fine and it is this check that is broken.
+      info(`Could not compare this machine against what the engine last recorded (${e?.message ?? e}). `
+        + `That comparison is what catches a settings page reading healthy while a search will not start, `
+        + `so this run has not checked it either way.`);
+    }
+
     // item 5 — WHICH BILLING LANE, reported rather than left to be inferred from a variable's
     // absence. `--check` named the engine and its binary and never said how the box pays, so the two
     // states that matter — metered per token, or drawn against a subscription — were indistinguishable
@@ -1366,7 +1612,7 @@ export async function runCheck() {
       // Both lines were honest about their own source and neither said what it was. The first reads this
       // command's env file; the second reads THIS PROCESS's resolution, and a CLI is started by a login
       // shell that carries none of the units' `EnvironmentFile`. The deployment was correct and served
-      // zephyr, aurora and generic throughout.
+      // the configured roster throughout.
       //
       // THE UNITS' ENV IS NOT PASSED INTO `profileStoreResolution`, deliberately. `PROFILES_OVERLAY_DIR`
       // is captured when profiles.mjs LOADS, so handing it the units' value would set `live` with no
@@ -1418,17 +1664,38 @@ export async function runCheck() {
         const demo = keys.filter((k) => roster.get(k)?.demoData === true);
         // `generic` is the universal fallback the module requires by name, not a brand owner somebody
         // onboarded — counting it would tell an operator with an empty store that they have one.
-        const owners = keys.filter((k) => k !== "generic");
+        //
+        // A DEMO ACCOUNT IS NOT AN ONBOARDED OWNER EITHER, and until this line it was counted as one. A
+        // fresh install used to ship the demo account into every roster, so `doctor` reported "1 brand
+        // owner(s) resolve here: demo-brand-owner (DEMO DATA)" on a machine where nobody had onboarded
+        // anything — and never named `generic`, which is the account that actually rates a run there.
+        // The reader is told they have a customer and not told what they are running on. Both halves
+        // wrong from one list.
+        //
+        // SINCE 2026-09-08 A FRESH INSTALL RESOLVES `generic` ALONE (owner ruling): nobody should have to
+        // clean demo material out of an environment they just created. So the demo branch below no longer
+        // fires on a plain install — it fires inside the demo, which asks for its own account. It is kept
+        // rather than deleted because it is still reachable, and a reader who meets the demo account
+        // there is owed the same two facts: it is fiction, and a real clearance under it is refused at
+        // the admission wall.
+        //
+        // Three states, told apart, because they mean three different things to whoever is reading:
+        // an onboarded roster, the house default alone, and the house default beside what the demo
+        // brought with it.
+        const owners = keys.filter((k) => k !== "generic" && !demo.includes(k));
         if (!owners.length) {
-          info(`no brand owners resolve here — only the \`generic\` fallback. An empty store is a working `
-            + `install on Generic defaults; it is also what a store pointed at the wrong directory looks like`);
+          const base = "`generic` is the account this install rates under — the house default, and the "
+            + "only one a clean install has";
+          if (demo.length) {
+            info(`${base}. The demo brought one with it, marked DEMO DATA: ${demo.join(", ")} — fiction `
+              + "rather than an account anybody onboarded, and a real clearance under one is refused");
+          } else {
+            info(`${base}. An empty store is a working install on Generic defaults; it is also what a `
+              + "store pointed at the wrong directory looks like");
+          }
         } else {
-          const marked = owners.map((k) => (demo.includes(k) ? `${k} (DEMO DATA)` : k)).join(", ");
-          const line = `${owners.length} brand owner(s) resolve here: ${marked}`;
-          // The demo marker is the member-level half: naming the store is not the
-          // same as saying the accounts in it are fiction, and a real clearance under one is refused at
-          // the admission wall — which an operator should learn here rather than from that refusal.
-          if (demo.length) info(`${line} — accounts marked DEMO DATA cannot start a real clearance`);
+          const line = `${owners.length} brand owner(s) resolve here: ${owners.join(", ")}`;
+          if (demo.length) info(`${line}. The demo brought one with it, marked DEMO DATA: ${demo.join(", ")} — not counted above, and a real clearance under one is refused`);
           else ok(line);
         }
         try {
@@ -2118,7 +2385,7 @@ export async function runCheck() {
     //
     // `describeDoorState` was written for exactly this block and then never called from it: the split
     // it encodes sat in `shared/client-door.mjs` with no caller in `bin/` or `driver/`, while doctor
-    // went on printing the three sentences the split replaces. The defect role-e2e measured is one of
+    // went on printing the three sentences the split replaces. The defect testing measured is one of
     // them — a `connect` that died at `daemon-reload` had already written the fence and placed both
     // units, and doctor said "the client door is on" over a unit that was inactive with nothing on its
     // port. Every angle read as configured, because configured is all anything asked.
@@ -2310,6 +2577,27 @@ export async function runCheck() {
         // unreachable; repeating it as a second failure teaches the reader that this section
         // double-counts. It still states what was NOT established, which is the whole job.
         else if (v.kind === "could-not-look") info(v.message);
+        // NO ACCESS IN FRONT OF THE CLIENT DOOR IS A POSTURE, NOT A FAULT (owner ruling 2026-09-08).
+        //
+        // This is the CLIENT connector's address, and how a client reaches it is the client's decision:
+        // "client access sitting behind OAuth is totally up to a client — plenty might just run it token
+        // based on their own laptop." A door answering with its own Bearer challenge and no Access front
+        // is a supported shape, not a misconfiguration, so raising it made `doctor` exit 1 on a healthy
+        // deployment and taught its reader to skim the one command that must never be skimmed.
+        //
+        // It is still SAID rather than dropped, and it still states what was not established: an
+        // audience that was never compared is not an audience that agreed. What changed is that the
+        // sentence no longer calls a client's own arrangement a finding about this install.
+        //
+        // Scoped deliberately to `not-fronted` on THIS address. A configured audience that DISAGREES
+        // with the one the edge issues is still a fault, and the portal and ops surfaces are untouched —
+        // they are checked elsewhere and Access in front of them is not optional.
+        else if (v.kind === "not-fronted") {
+          info(`nothing is fronting this hostname with Access — ${read.why}. That is this client door's `
+            + "posture rather than a fault: a client may reach it with its own token and no Access in "
+            + "front, which is a supported shape. The configured audience was not compared against this "
+            + "address, so nothing here says the two agree.");
+        }
         else problem(v.message);
       }
     }
@@ -2534,13 +2822,13 @@ try {
 
   // 1 ── Node
   say("  Node");
-  const major = Number(process.versions.node.split(".")[0]);
-  if (major < NODE_FLOOR) {
-    problem(`node ${process.versions.node} — this engine needs >= ${NODE_FLOOR}. Upgrade Node and run setup again.`);
+  const nodeV = nodeFloorVerdict();
+  if (!nodeV.ok) {
+    problem(`node ${nodeV.current} — this engine needs ${nodeV.required} or newer. Upgrade Node and run setup again.`);
     aborted = "node";
     throw new Error("node floor");
   }
-  ok(`node ${process.versions.node}`);
+  ok(`node ${nodeV.current}`);
 
   // 2 ── the engine: which one, which binary, and PROOF that it can run a turn
   //
@@ -2570,7 +2858,32 @@ try {
     if (!pick.id) { sayNoEngine(); break; }
     const eng = ENGINE_BINARIES[pick.id];
 
+    // ── NATIVE WINDOWS IS ANSWERED HERE TOO, AND THE ESCAPE IS OFFERED RATHER THAN LEFT ON A MENU ──
+    //
+    // Doctor learned this and the wizard did not, and the gap is worse than it sounds: the two "no
+    // engine" escapes below both sit behind "no usable binary", and on Windows that is FALSE. X_OK is
+    // satisfied by any file that exists, so the wizard says "found C:\...\claude", walks past both
+    // escapes, asks which lane pays, spends a proof turn, and meets `spawn claude ENOENT`. The only
+    // prompt left then defaults to No and returns to the engine menu — with nothing changed between
+    // iterations, on either lane. Reported from a real Windows run: the menu's last row was the one
+    // way out and nothing on screen said so.
+    //
+    // So the refusal is stated before a candidate is resolved, and finishing with no engine is OFFERED
+    // rather than being a row the reader has to notice. Declining leaves them on the menu exactly as
+    // before, which is the branch that was already there.
+    const wizardRefusal = platformEngineRefusal();
+    if (wizardRefusal) {
+      problem(wizardRefusal);
+      if (await confirm("Finish setup with no engine configured?", true)) { sayNoEngine(); break engine; }
+      continue;
+    }
+
     let bin = resolveEngineBin(process.env[eng.env] || eng.fallback);
+    // Under WSL the Windows build on the appended PATH has been passed over. Said before the install
+    // offer below, because otherwise a reader whose Linux install is genuinely missing is asked to
+    // install a binary their own `which` already prints — and would decline for the wrong reason.
+    const shimNote = windowsShimNote(bin.skipped, eng.fallback);
+    if (shimNote) info(shimNote);
     if (!(bin.executable && !bin.relative) && eng.install) {
       // ── — INSTALLING IT IS ONE COMMAND, AND WE USED TO STOP AT A SENTENCE ───────────────────
       //
@@ -2769,7 +3082,20 @@ try {
         break engine;
       }
       problem(probeFailureText(v));
+      // ── THE ENGINE'S OWN LAST LINES, UNDER EVERY VERDICT, ON BOTH LANES ──────────────────────────
+      //
+      // This used to be `if (v.detail)`, so a verdict carrying no detail printed a headline and nothing
+      // else — and the reader had a classification with no evidence to check it against. That is the
+      // worst shape for a heuristic: the signed-out test is a text match over the engine's output, it
+      // matches broadly on purpose, and a reader shown only its conclusion cannot tell a genuinely
+      // signed-out CLI from an unrelated failure whose words happened to match.
+      //
+      // SAY WHICH IT IS, INCLUDING WHEN THERE IS NOTHING. "The engine printed nothing" is itself the
+      // diagnosis on a binary that died before it opened its mouth, and printing no line at all leaves
+      // a reader unable to tell that from a wizard that decided not to show them.
       if (v.detail) info(`engine said: ${v.detail}`);
+      else info("engine said: nothing — it produced no output on either stream before it stopped.");
+      if (v.basis) info(`(that reading is ${v.basis === "text-match" ? "matched out of the text above, not a signal from the provider" : v.basis})`);
       // — THE HAND-OFF. Signing in is the one step of this sequence nobody here can perform for
       // someone, so the wizard names the command, waits, and re-probes rather than ending at a
       // description of what is wrong. The text comes from ENGINE_BINARIES so the two adapters cannot
@@ -3175,6 +3501,22 @@ try {
   say("  fallback — falls through by name, so an empty store is a working install. Your own customers");
   say("  are added here by name; the bundled demo customers never show through into your roster.");
 
+  // 7c ── WHO SIGNS IN, AND WHAT THAT ADDRESS GRANTS
+  //
+  // Setup never asked for an address, so `clearotron start` derived one — and derived a staff-domain
+  // rule from everything after its `@`. The whole reasoning, and the install that granted a
+  // documentation domain to a reader who had never been asked, is on `askSignIn` above.
+  section("Who signs in");
+  const localAccount = (() => {
+    try { return userInfo().username || "user"; } catch { return "user"; }
+  })();
+  // ONE CALL SITE. The loop itself lives in `askSignIn` so that the branch that matters — a reader who
+  // pressed Enter at the grant question, and a staff rule that must therefore NOT be written — is
+  // reachable without a terminal. The same seam and the same reason as `offerUsptoSync`.
+  Object.assign(candidate, await askSignIn(
+    { askValue, confirm, say, ok, info, warn, problem },
+    { localAccount, staffLabel: `${BRAND.name} staff`, envPath: ENV_PATH }));
+
   // 8 ── the engine's own preflight over the whole candidate
   //
   // — THIS STEP CHECKS THE REGISTER PROVIDER AND NOTHING ELSE. `preflightCandidate` pins