clearotron 0.3.2-beta.10 → 0.3.2-beta.12

package/bin/onboard.mjs

@@ -1030,6 +1030,31 @@ export function installSizeLine(eng) {
   return `${Number.isFinite(eng?.installMB) ? `It takes about ${eng.installMB} MB. ` : ""}To remove it, delete that folder.`;
 }
 
+/**
+ * Whether a login shell will put `dir` on the PATH: some profile this user's shells read names it.
+ *
+ * Setup promised "open a new login shell, and plain `clearotron start` works". That is Ubuntu's stock
+ * `~/.profile` for an ordinary user, which adds `~/.local/bin` once it exists. It is not root's in a fresh
+ * container, measured on ubuntu:24.04 by an outside install, and it is not macOS's default zsh. So the
+ * promise is made only when a profile names the directory. A profile that adds it some other way reads as
+ * "no", which costs a reader one line of advice and never sends them to a shell that will not find it.
+ */
+const LOGIN_PROFILES = [".profile", ".bash_profile", ".bash_login", ".bashrc", ".zprofile", ".zshenv", ".zshrc", ".zlogin"];
+export function aLoginShellAdds(dir, { home = homedir(), read = (p) => readFileSync(p, "utf8") } = {}) {
+  const d = String(dir ?? "");
+  if (!d) return false;
+  const rel = home && d.startsWith(`${home}/`) ? d.slice(home.length + 1) : null;
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = new RegExp(`(^|[^\\w.-])(${esc(d)}${rel ? `|(\\$HOME|\\$\\{HOME\\}|~)/${esc(rel)}` : ""})(?![\\w.-])`);
+  for (const f of LOGIN_PROFILES) {
+    let text;
+    try { text = read(join(home, f)); } catch { continue; }
+    // A COMMENTED-OUT LINE ADDS NOTHING, and a disabled PATH line is an ordinary state for a profile.
+    if (String(text ?? "").split("\n").some((l) => !/^\s*#/.test(l) && names.test(l))) return true;
+  }
+  return false;
+}
+
 /**
  * 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.
@@ -1997,7 +2022,7 @@ export async function runCheck() {
       info(`this install's own is ${form.shim} — the commands below name it in full, so they reach THIS install`);
     } else if (form.form === "shim-path") {
       warn(`${form.dir} is not on this shell's PATH, so the bare \`clearotron\` will not resolve here`);
-      info(`add it with: export PATH="${form.dir}:$PATH"  — or open a new login shell`);
+      info(`add it with: export PATH="${form.dir}:$PATH"${aLoginShellAdds(form.dir) ? "  — or open a new login shell" : ""}`);
     } else if (form.form === "npx-pinned") {
       info(`this is running from npm's npx cache, so the commands below name this version through npx (\`${form.prefix.trim()}\`), `
         + `which works from any directory and after npm cleans its cache; \`${invoke("install")}\` puts \`clearotron\` on your PATH`);
@@ -2793,6 +2818,9 @@ export async function runCheck() {
       info(`the units are installed but their environment could not be read (${unitEnv?.why ?? "no reason given"}) — `
         + "the door verdicts below are withheld rather than guessed, because a failure to look is not a finding");
     if (door.shape === "local") {
+      // WHO THAT ONE USER IS, in the owner's words (2026-09-19), resolved as `start` resolves it.
+      const oneUser = String(effectiveForService("PORTAL_LOCAL_USER")?.v || `${userInfo().username}@localhost`).trim().toLowerCase();
+      say(`  · Portal sign-in: one user, ${oneUser}, by passphrase.`);
       say(`  · local passphrase door (${typed}) — one operator, one passphrase, no identity provider`);
       info(`a lost passphrase is recoverable: ${invocationPrefix()}clearotron passphrase --reset`);
     } else if (door.shape === "fronted") {
@@ -3169,7 +3197,10 @@ export async function runCheck() {
         try { const s = statSync(p); if (s.size > 0) { wrote = p; break; } } catch { /* not this one */ }
       }
       if (wrote) {
-        ok(`the client door's access log is being written: ${wrote}`);
+        // WHAT WAS READ, AND NOTHING MORE. This said "is being written" from any non-empty file — a claim
+        // about activity made from a file's size, printed over a log whose only line was a test's
+        // (measured 2026-09-19). Reworded as the owner ruled, 2026-09-19.
+        ok(`the client door's access log has entries: ${wrote}`);
       } else {
         // NOT-YET-WRITTEN IS NOT UNWRITABLE. A door nobody has called through has no log, and saying it
         // is broken would be the same lie as calling an unreachable unit inactive.
@@ -4029,20 +4060,25 @@ try {
   say("\n  Register provider");
   say("  This decides which register gets searched, and which vendor gets billed. There is no default in");
   say("  the engine — it refuses to guess.");
-  const provider = await choose("Which register?", PROVIDERS.map((p) => ({ label: `${p.label} — ${p.cost}`, spec: p })), 0);
+  // THE LAST ROW IS NOT A REGISTER, as on the AI question, and with the same words. Leaving the register
+  // unset was reachable only by picking a vendor and skipping its credential, so a reader who meant "none
+  // yet" had to pretend to choose one. Choosing it takes the branch a skipped credential reaches below.
+  const provider = await choose("Which register?", [...PROVIDERS.map((p) => ({ label: `${p.label} — ${p.cost}`, spec: p })), { label: "None for now", spec: null }], 0);
   const spec = provider.spec;
-  say(`\n  ${spec.label}: covers ${spec.covers}`);
-  for (const w of spec.warnings ?? []) warn(w);
-  if (spec.signup && !spec.credentials.every((k) => present(candidate[k]))) {
-    say("\n  How to get a credential:");
-    for (const l of spec.signup) say(`    ${l}`);
-    say("");
+  if (spec) {
+    say(`\n  ${spec.label}: covers ${spec.covers}`);
+    for (const w of spec.warnings ?? []) warn(w);
+    if (spec.signup && !spec.credentials.every((k) => present(candidate[k]))) {
+      say("\n  How to get a credential:");
+      for (const l of spec.signup) say(`    ${l}`);
+      say("");
+    }
   }
   // ── — INSTALL MAY FINISH WITH NO REGISTER. Ruling, 2026-08-26 ──────────────────────
   //
   // Every row of PROVIDERS declares required credentials, and this prompt had no way out, so a reader
-  // with no vendor account could not reach the closing screen at all — the menu offers no "none" row,
-  // which means they arrive here without ever having chosen to supply a key.
+  // with no vendor account could not reach the closing screen at all. The menu's "None for now" row is
+  // the chosen way here; a skipped credential is the other.
   //
   // A REGISTER IS ALL-OR-NOTHING, WHICH IS WHY ONE SKIP ABANDONS THE WHOLE SELECTION. Half a credential
   // pair is not a working register; writing CLEAROTRON_DATABASE beside it would name an adapter that
@@ -4053,14 +4089,14 @@ try {
   // is single-valued with no default, a run already refuses by name when it is unset
   // (driver.config.mjs), and the Installation settings page already says a register is needed.
   // One register per install, any one of them sufficient, none a precondition for another.
-  let registerSelected = true;
+  let registerSelected = spec != null;
   // What THIS step collected, so abandoning the selection can take it back. Measured: a register with
   // two required credentials — `euipo`, `free-tier` — let a reader supply the first and skip the second,
   // and the first was written to the .env with no CLEAROTRON_DATABASE beside it. `candidate` is
   // serialised wholesale at the write step, so anything left in it ships. A credential for a register
   // nobody selected is a secret persisted for a decision that was reversed.
   const collectedHere = [];
-  for (const k of spec.credentials) {
+  for (const k of spec?.credentials ?? []) {
     if (present(candidate[k])) { ok(`${k} already adopted from your environment`); continue; }
     const v = await askValue(`${k}:`, { secret: true, skippable: true,
       skipped: `${k} not set, so ${spec.id} cannot be configured — this install will have NO register selected.` });
@@ -4581,7 +4617,8 @@ try {
     say(`  \`clearotron\` is now installed at ${form.shim}, and ${form.dir} is not on this shell's`);
     say("  PATH yet — most login profiles add it only if it existed when the shell started. So:\n");
     say(`    export PATH="${form.dir}:$PATH"     # this terminal, now`);
-    say("      …or open a new login shell, and plain `clearotron start` works from anywhere.\n");
+    if (aLoginShellAdds(form.dir)) say("      …or open a new login shell, and plain `clearotron start` works from anywhere.\n");
+    else say("");
   } else if (form.form === "in-place") {
     say("  There is no `clearotron` on your PATH, so the commands above name the directory to run them");
     say("  from. Re-run the install to put the verb on your PATH.\n");

package/bin/passphrase.mjs

@@ -32,6 +32,7 @@ import { defaultInstallBase, establishCredential, installCredential, readLocalCr
 // rather than hardcoded. A hardcoded `npx ` tells a global installer their install is somehow lesser;
 // a hardcoded bare name sends an npx reader to `command not found`.
 import { invocationPrefix } from "../shared/invocation.mjs";
+import { BRAND } from "../shared/brand.mjs";
 
 const P = invocationPrefix();
 const USAGE = `  ${P}clearotron passphrase — report or reset the portal's local sign-in
@@ -117,8 +118,9 @@ catch (e) {
   process.exit(1);
 }
 
-console.log(`\n  A NEW passphrase has been minted for ${email}.`);
-console.log(`  The previous one no longer works.\n`);
+// THE OWNER'S WORDS, 2026-09-19: what the value is for comes before it, and names the one user it signs in.
+console.log(`\n  New passphrase for this ${BRAND.name}'s one user, ${email}. Paste it on the portal's sign-in page:\n`);
 console.log(`  PASSPHRASE: ${minted.passphrase}\n`);
+console.log(`  The previous one no longer works.`);
 console.log(`  Write it down now. It is stored only as a digest, so this line is the only copy that will`);
 console.log(`  ever exist — re-run this command if you lose it.\n`);

package/bin/start.mjs

@@ -121,7 +121,7 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 // — the door --background now INSTALLS, and the one authority for the settings
 // it refuses to start without. (Until 2026-09-03 this import read "the one unit --background may
 // tolerate and never manage"; settled point 2 superseded that.)
-import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
+import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand, demoConnectCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
 import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
@@ -805,6 +805,10 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // DNS-rebinding protection is keyed off this list being non-empty, so it is derived from the same
       // port the listener is given rather than left to whoever remembers.
       TRADEMARK_MCP_ALLOWED_HOSTS: `${host}:${ports.mcp},localhost:${ports.mcp}`,
+      // WHERE THE OTHER DOOR IS, so a key refused here is told where it belongs (shared/scope.mjs
+      // otherDoor). Read by nothing else in this process.
+      CLIENT_MCP_HTTP_HOST: host,
+      CLIENT_MCP_HTTP_PORT: String(ports.client),
     },
     // The worker needs the install's PATHS and nothing else — no ports, no secrets, no door config. It
     // talks to the queue and the pool, not to either listener.
@@ -830,6 +834,9 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // written in one place and an allow-list in another drift into a door that starts and turns every
       // request away, which reads as a dead door rather than as a misconfiguration.
       CLIENT_MCP_ALLOWED_HOSTS: `${host}:${ports.client},localhost:${ports.client}`,
+      // The staff door's place, for the mirror refusal (shared/scope.mjs otherDoor). Read by nothing else here.
+      TRADEMARK_MCP_HTTP_HOST: host,
+      TRADEMARK_MCP_HTTP_PORT: String(ports.mcp),
       CLIENT_MCP_ACCOUNT_ACCESS: String(clientFence ?? "1"),
       // TOKEN-ONLY, AND WITHOUT IT THE DOOR DOES NOT START. Found by driving it rather than by reading
       // the diff: with this unset the door demands an OIDC audience plus a Cloudflare Access team or
@@ -2322,7 +2329,7 @@ if (isMain) {
   // Captured HERE, immediately before the spawn, rather than beside the sentence that reads it: the
   // check has to sit on the other side of the thing that mints, and the only way to keep that true is
   // for it to be adjacent to the spawn where a reader can see why.
-  const { credentialPathFor: credentialPathBeforeStart, newPassphrase, passphraseResetCommand, demoCredentialToReplace, laterStartLines, readLocalCredential } = await import("../driver/portal-local-auth.mjs");
+  const { credentialPathFor: credentialPathBeforeStart, newPassphrase, passphraseResetCommand, passphraseWithheldLines, demoCredentialToReplace, laterStartLines, readLocalCredential } = await import("../driver/portal-local-auth.mjs");
   // ASKED ABOUT THE FILE THE PORTAL WILL ACTUALLY USE, not the shared default. `credentialPathFor`
   // reads `PORTAL_LOCAL_CREDENTIAL`, and a demo sets it to a file inside its own base — but this call
   // was made against THIS process's environment, which never carries it. So on any box that already had
@@ -2421,7 +2428,8 @@ if (isMain) {
   // The output used to name neither as a door, so an owner watching one of them start concluded MCP had
   // not come up. Both are printed with who each is for, because "MCP is running" is ambiguous on a box
   // that has two of them and the ambiguity is what cost the leg.
-  say(`  Engine door  http://${HOST}:${ports.mcp}/mcp   — the portal's Start button calls this. Staff.`);
+  // THE CLIENT DOOR LEADS (owner, 2026-09-19). It is the one an assistant uses, and with the engine door
+  // printed first a demo's reader handed the staff address to their assistant, which refused its key.
   // THE SYNCHRONOUS TRUTH, NOT THE ASYNC FLAG ( — F26, review finding).
   //
   // `rec.alive` is flipped by the child's exit handler, which is async: reading it here asks "has the
@@ -2440,11 +2448,12 @@ if (isMain) {
     if (adoptedClientDoor)
       say(`               Already running as ${CLIENT_DOOR_UNIT}; this start kept it, so existing keys still work.`);
     else
-      say(`               It refuses every caller until a key is issued: ${keyIssueCommand({ prefix: invocationPrefix(), demo: DEMO, user, base: paths.base, defaultBase: join(homedir(), "trademark") })}`);
+      say(`               It refuses every caller until a key is issued: ${DEMO ? demoConnectCommand({ prefix: invocationPrefix(), base: paths.base }) : keyIssueCommand({ prefix: invocationPrefix(), demo: DEMO, user, base: paths.base, defaultBase: join(homedir(), "trademark") })}`);
   } else {
     say(`  Client door  NOT RUNNING on ${HOST}:${ports.client} — its output above says why. The portal and`);
     say("               the engine door are unaffected; a client assistant cannot connect until it is up.");
   }
+  say(`  Engine door  http://${HOST}:${ports.mcp}/mcp   — the portal's Start button calls this. Staff.`);
   say("");
   // ── WHAT `status` AND `stop` READ ABOUT THIS START ───────────────────────────────────────────────
   //
@@ -2486,16 +2495,25 @@ if (isMain) {
   // line is what a reader copies when they lose the passphrase — run as printed, the bare form resolved
   // the shared default and exited 1 saying no credential exists.
   const reset = passphraseResetCommand({ prefix: invocationPrefix(), credentialPath: envs.portal.PORTAL_LOCAL_CREDENTIAL ?? null });
+  // ── ONLY A TERMINAL IS HANDED THE PASSPHRASE ──────────────────────────────────────────────────────
+  //
+  // The first-start box went to standard output whatever standard output was. Under a service manager,
+  // `nohup` or `> start.log` that is a file, so the one value this product cannot read back landed in a
+  // log, a moment after the portal's own line said it was being withheld for exactly that reason.
+  // Measured on a published beta by an outside install. A redirected run gets the portal's own words
+  // instead, from the composer the portal uses, and the way to mint one on a terminal.
   if (mintedPassphrase) {
     const rule = "─".repeat(66);
     say(`  ┌${rule}┐`);
     say(`  │  Open        ${envs.url}`);
     say(`  │  Sign in as  ${user}`);
-    say(`  │  Passphrase  ${mintedPassphrase}`);
-    say(`  │`);
-    say(`  │  WRITE THE PASSPHRASE DOWN NOW. It is stored only as a digest, so`);
-    say(`  │  nothing — not this product, not this terminal — can read it back.`);
-    say(`  │  Lost it? ${reset}`);
+    if (process.stdout.isTTY === true) {
+      say(`  │  Passphrase  ${mintedPassphrase}`);
+      say(`  │`);
+      say(`  │  WRITE THE PASSPHRASE DOWN NOW. It is stored only as a digest, so`);
+      say(`  │  nothing — not this product, not this terminal — can read it back.`);
+      say(`  │  Lost it? ${reset}`);
+    } else for (const line of passphraseWithheldLines({ stream: "stdout", resetCommand: reset }).flatMap((l) => (/^\s/.test(l) ? [l] : fitTo(64, l)))) say(`  │  ${line}`);
     // THE HINT BELONGS IN THE BOX TOO, and this was the reader the whole sentence was written for. The
     // frame exists because a first-time reader skips the log wall and acts on it — so the one address
     // they copy was the one address with nothing beside it saying what to do when the page that opens
@@ -2604,6 +2622,22 @@ export function demoBaseIsTheReaders({ baseGiven = false, ownBase = false, base
   return !(ownBase && base && demoDefault && base === demoDefault);      // handed over, and it IS the default
 }
 
+/**
+ * A sentence broken at spaces into lines of at most `width` characters, for the framed box. The withheld
+ * lines come from the portal's composer, written for a log line of any length; inside the frame they are
+ * broken to the width of the lines they stand in for. A word longer than `width` keeps its own line. PURE.
+ */
+export function fitTo(width, text) {
+  const out = [];
+  let line = "";
+  for (const word of String(text ?? "").split(/\s+/).filter(Boolean)) {
+    if (line && line.length + 1 + word.length > width) { out.push(line); line = word; }
+    else line = line ? `${line} ${word}` : word;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
 export function demoBaseResetTarget({ baseGiven = false, base = "", demoDefault = "" } = {}) {
   if (baseGiven) return null;                      // the reader chose it, so it is not the demo's to clear
   if (!base || !demoDefault) return null;          // nothing to compare: say no

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1c5ecbdefb9e379d1a7407aabfd3efc9384ffa44",
-  "version": "0.3.2-beta.10"
+  "commit": "92dc979bd176adeedc0dbe2518fbf24388bc6072",
+  "version": "0.3.2-beta.12"
 }

package/docs/architecture/05-config-governance.md

@@ -542,7 +542,7 @@ change. The product's known mirror classes:
 | CF Access team / AUD / domain gates | edge (dashboard) + each fronted unit's inline env | staff or company lockout, service by service |
 | `TRADEMARK_MCP_TOKEN_SECRET` | EnvironmentFile + any integrator-hosted artifacts-MCP env block | run-bound `user` tokens fail verification |
 | Register-provider credentials | EnvironmentFile + integrator plugin config (when both consume the provider) | one consumer silently unauthenticated |
-| Profiles/skills store paths | EnvironmentFile + service unit files (+ integrator MCP env) | roster-mismatch class (the PR #14 incident) |
+| Profiles/skills store paths | EnvironmentFile + service unit files (+ integrator MCP env) | roster-mismatch class: a door serving the bundled demo roster instead of the real one |
 | Pool root | code default + units + web-server file root (+ integrator MCP env) | reports publish where nothing serves |
 | Public hostnames | EnvironmentFile (rendered links) + router + edge | dead links / dead routes |