clearotron 0.2.4 → 0.3.0-beta.1

package/bin/start.mjs

@@ -5,6 +5,9 @@
 //
 //   npx clearotron start                  start the portal and the trigger lane; print one URL
 //   npx clearotron start --user you@host  the one address that signs in (persisted; asked for once)
+//   npx clearotron start --organisation <name>
+//                                        your organisation's name, filed in a grants file that holds
+//                                        none yet (setup asks for it; unset, none is invented)
 //   npx clearotron start --base <dir>     where this install keeps its data (default ~/trademark)
 //   npx clearotron start --port <n>       the portal's port (default 18802); the engine door takes
 //                                        n+1 and the client door n+2 unless each is set explicitly
@@ -124,15 +127,19 @@ import { unitEnvPath } from "../shared/env-local.mjs";   // — the file the uni
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { usageBlock } from "../shared/usage-block.mjs";   // tracker issues 1861/1882
+import { usageBlock } from "../shared/usage-block.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
 import { productIdentity } from "../shared/product-identity.mjs";   // AGPL §13 — one answer, three surfaces
 import { pinEnvAll } from "../shared/env-aliases.mjs";   // — a pin that names one spelling has set nothing that wins
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
 import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // never serve a bundle older than its sources
-// ONE CLASSIFIER FOR WHAT A STAFF RULE ADMITS, shared with the setup wizard. Two copies of this
-// judgement would be a wizard that asks about one rule and a launcher that writes another.
-import { classifyStaffDomain, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
+// THE REFUSALS ABOUT THE SIGN-IN ADDRESS ITSELF, shared with the setup wizard so the two cannot send
+// back different addresses.
+import { addressRefusal } from "../shared/staff-domain.mjs";
+// The grants file's editors, shared with `clearotron grant` and the portal's People page: the installer's
+// entry is written through them, so this command cannot produce a shape of its own.
+import { withPerson, withOrganisation } from "../shared/grants-edit.mjs";
+import { assertGrantsShape, resolvePerson } from "../shared/scope.mjs";
 import { backgroundManager } from "../shared/os-advice.mjs";
 import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
@@ -175,7 +182,7 @@ export function homeEnvUpdate(homeText, union) {
 }
 
 /**
- * What a `--background` run has ALREADY DONE when systemd refuses to enable a unit — tracker issue 203.
+ * What a `--background` run has ALREADY DONE when systemd refuses to enable a unit.
  *
  * THE READER'S QUESTION IS NOT THAT A STEP FAILED. It is whether they now have a half-installed
  * deployment, and whether to run this again, undo it, or leave it alone. This step is the worst-placed
@@ -214,7 +221,7 @@ const HOST = "127.0.0.1";
 // ── pure helpers (exported for driver/test/start-command.test.mjs) ───────────────────────────────────
 
 /**
- * WHOSE socket is on the client door's port — tracker issue 228.
+ * WHOSE socket is on the client door's port.
  *
  * `clearotron stop` removes three units and DELIBERATELY leaves the client door running, because a
  * product stop must not silently revoke an assistant's connection. `start` then manages that same door
@@ -294,7 +301,7 @@ export function resolvePorts(env = {}) {
 }
 
 /**
- * Apply `--port <n>` to the three doors — tracker issue 166.
+ * Apply `--port <n>` to the three doors.
  *
  * PURE, AND EXPORTED, because the inline version of this could only be tested by spawning a supervisor
  * and reading `ss`. The defect it fixes was found by a reader watching a log line, which is exactly
@@ -371,74 +378,43 @@ export function installPaths(base) {
   };
 }
 
-/** A staff rule this command will not build. Carries the sentence the operator reads, and why. */
-export class StaffDomainRefused extends Error {
-  constructor(domain, message) { super(message); this.name = "StaffDomainRefused"; this.domain = domain; }
-}
-
 /**
- * The one address that signs in, and the staff domain derived from it.
+ * The grants file after this start has made sure the person who installed can use the install.
  *
- * Derived, never asked twice. In local mode the portal admits EXACTLY ONE address, so a domain-wide
- * staff rule built from that address admits exactly that address and nobody else — which is what makes
- * it safe here and would not be safe on a hosted instance. Without it the sign-in succeeds and every
- * page 403s, because signing in is not being enrolled (portal-access.mjs decides that, and it is
- * deliberately blind to which door you came through).
+ * THE PERSON WHO INSTALLS IS THE FIRST PERSON: Run, Manage, access to everything. That used to be derived
+ * from the part of their address after the `@` — a domain rule that admitted exactly one identity on
+ * `<account>@localhost` and a whole employer on anything else. The rule is deleted. The installer is an
+ * entry of their own under `people`, and nothing about a domain admits anyone.
  *
- * ── AND THAT PARAGRAPH IS ONLY TRUE OF `<account>@localhost` ─────────────────────────────────────────
+ * TWO CONDITIONS, DECIDED SEPARATELY:
  *
- * "admits exactly that address and nobody else" is a property of the DOMAIN, not of the mode. It holds
- * for `localhost`. It does not hold for a domain other people have addresses at: the rule this line
- * produces from `alex@a-firm.example-tld` says *anyone at that domain*, the settings page then reports
- * it back in those words, and on a deployment where identity arrives from an external login system the
- * domain is the whole of the check. Nobody was asked, and there is nothing on the box recording that a
- * grant was made.
+ *   the installer's entry   written when the file names nobody under `people` — a fresh file, and the
+ *                           `{"tenants":{}}` this command wrote before `people` existed, whose local user
+ *                           was admitted by the domain rule and would otherwise be locked out of their own
+ *                           install on the first start after an upgrade. A file that names anybody is
+ *                           somebody's decision, and it is left exactly as it is.
+ *   the first organisation  created when the file holds no organisation and a name is known. Absent a
+ *                           name, none is invented: a person with access to everything resolves without
+ *                           any organisation, and Generic then files under none, which is how every
+ *                           Generic run was filed before organisations existed.
  *
- * So the derivation now refuses the domains that can never be a staff rule — a webmail provider, a
- * documentation domain — and hands anything wider than one machine back to the caller to state and
- * confirm. `shared/staff-domain.mjs` is the one classifier, shared with the setup wizard, so the
- * question the wizard asks and the rule this command builds cannot drift apart.
- *
- * An UNPARSEABLE address still returns `""`, and that is not the same answer as a refusal: nothing was
- * classified, so nothing was decided. The caller already refuses a non-address one line earlier.
+ * PURE, so the policy can be DRIVEN rather than read — the reason `homeEnvUpdate` is extracted: the start
+ * that writes this binds ports and spawns children. `unadmitted` says the address resolves to no access
+ * in the result; the caller reports that rather than repairing it.
  */
-export function staffDomainFor(email) {
-  const at = String(email ?? "").lastIndexOf("@");
-  const domain = at > 0 ? String(email).slice(at + 1).toLowerCase() : "";
-  if (!domain) return "";
-  const refusal = staffDomainRefusal(domain);
-  if (refusal) throw new StaffDomainRefused(domain, refusal);
-  return domain;
-}
-
-/**
- * What to say when the derived domain is a real one — wider than this machine, and never assumed.
- *
- * A REFUSAL RATHER THAN A PROMPT, and the reason is that this command has no reader. `start` runs from
- * a script, from `--background`, and from a service manager as often as from a terminal; a question
- * asked there either hangs or is answered by whatever happens to be on stdin. Every other decision on
- * this boundary already refuses instead — an unset access file, a multi-`@` identity, local mode off
- * loopback — so this is the idiom the rest of the door speaks.
- *
- * The consent itself lives where a person is definitionally present: `clearotron install` asks for the
- * address, shows this same sentence, and writes the answer down as an explicit `PORTAL_STAFF_DOMAINS`.
- * After that the `||` above this call short-circuits and the derivation is never reached again.
- */
-export function wideStaffDomainRefusal({ user, domain, envPath }) {
-  return `${user} would make every address at ${domain} an administrator of this install.\n`
-    + "\n"
-    + `  The rule that would be written is:  ${staffGrantSentence(domain, { staffLabel: `${BRAND.name} staff` })}\n`
-    + "\n"
-    + "  That is a grant to a group, and this command will not make one on your behalf. Pick the one\n"
-    + "  that is true here:\n"
-    + "\n"
-    + `    · only you use this machine — start without --user, or use ${String(user).slice(0, String(user).lastIndexOf("@"))}@localhost.\n`
-    + `      The rule is then this machine and nobody else, and nothing is granted to anyone.\n`
-    + `    · your colleagues at ${domain} should all be administrators — say so once, in writing:\n`
-    + `        PORTAL_STAFF_DOMAINS=${domain}\n`
-    + `      in ${envPath}, or in the environment. The settings page then names that file as where the\n`
-    + "      rule came from, so whoever reads it later can undo it.\n"
-    + `    · run \`${invocationPrefix()}clearotron install\`, which asks for the address and this question with it.`;
+export function installerGrants(existing, { user, organisation = null }) {
+  let grants = existing ?? { tenants: {} };
+  const changed = [];
+  if (!Object.keys(grants.people ?? {}).length) {
+    grants = withPerson(grants, { email: user, switches: { run: true, manage: true, everything: true } });
+    changed.push("person");
+  }
+  const name = String(organisation ?? "").trim();
+  if (name && !Object.keys(grants.tenants ?? {}).length) {
+    ({ grants } = withOrganisation(grants, { name }));
+    changed.push("organisation");
+  }
+  return { grants, changed, unadmitted: resolvePerson(user, grants) === null };
 }
 
 /**
@@ -495,7 +471,7 @@ export const BACKGROUND_RETIRED = Object.freeze([]);
 export const BACKGROUND_EXCLUDED = Object.freeze({
   // ── `clearotron-client-mcp.service` LEFT THIS TABLE ON 2026-09-03, AND SAYING SO IS THE POINT ────
   //
-  // It was the rebuild-seam gate of record (owner rulings, tracker issues 1976/2082): starting the unit
+  // It was the rebuild-seam gate of record (rulings): starting the unit
   // WAS the on-demand consent, because starting it turned on client-account access, so an enable list
   // that included it would have made that consent meaningless. That reasoning was right under that
   // ruling and the exclusion was not an oversight.
@@ -514,7 +490,7 @@ export const BACKGROUND_EXCLUDED = Object.freeze({
   "profile-service.service": "the portal constructs the profile service IN-PROCESS (driver/portal-service.mjs); the standalone unit is the separate-editor deployment shape and running both double-serves the store",
 });
 
-export function childEnv({ ports, paths, user, staffDomains, portalSecret, tokenSecret, opsToken, host = HOST, localWorker = false, demo = false, clientFence = null, env = process.env }) {
+export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken, host = HOST, localWorker = false, demo = false, clientFence = null, env = process.env }) {
   // ONE AUTHOR FOR THIS EXPRESSION. The hosted install path composes the same
   // origin, and the near-miss is specific: this is an ORIGIN, the portal's client appends `/mcp`
   // itself, and a second author writing the endpoint form produces a doubled path — a 404 at submit
@@ -577,7 +553,7 @@ export function childEnv({ ports, paths, user, staffDomains, portalSecret, token
     worker: { ...shared },
     // ── THE CLIENT DOOR, ON BOTH PATHS ( — F26) ──────────────────────────────
     //
-    // Owner ruling, restated several times in session: START BOTH. It already held on the systemd path
+    // Ruling, restated several times in session: START BOTH. It already held on the systemd path
     // — the door is in SERVER_INSTALL_SET on the 2148 ruling that the door auto-starts and the
     // PER-ACCOUNT KEY is the gate — and it did not hold on the foreground path, with nothing saying
     // which of the two you were on. The owner spent the leg believing MCP had not started at all; it
@@ -628,7 +604,6 @@ export function childEnv({ ports, paths, user, staffDomains, portalSecret, token
       ...shared,
       PORTAL_AUTH_MODE: "local",
       PORTAL_LOCAL_USER: user,
-      PORTAL_STAFF_DOMAINS: staffDomains,
       PORTAL_SECRET: portalSecret,
       PORTAL_SERVICE_HOST: host,
       PORTAL_SERVICE_PORT: String(ports.portal),
@@ -637,7 +612,7 @@ export function childEnv({ ports, paths, user, staffDomains, portalSecret, token
       PORTAL_OPS_TOKEN: opsToken,
       // — the demo runs THIS portal, not a second one. What that difference IS
       // has changed: the products are orderable and the confirmation resolves to a report that already
-      // exists (owner ruling 2026-08-31 14:47, superseding the greyed-control ruling of 14:44).
+      // exists (ruling 2026-08-31 14:47, superseding the greyed-control ruling of 14:44).
       //
       // The FLAG moved to `shared` and is `CLEAROTRON_DEMO`, because the
       // portal is no longer the only process that has to know: the MCP door prints a boot warning aimed
@@ -687,7 +662,7 @@ if (isMain) {
   const markStateWritten = () => { wroteState = true; };
   // `stated` is a caller that has already said what stands, in terms this generic line cannot reach —
   // which unit refused, which ones are up, what re-running does. Without it the systemd refusal printed
-  // both, and the pair read as two different answers to the reader's one question (tracker issue 203).
+  // both, and the pair read as two different answers to the reader's one question.
   const fatal = (msg, { stated = false } = {}) => {
     err(`\nstart: ${msg}\n`);
     if (wroteState && !stated) err("  This run had already written state (env file, data directories, grants, seeded example).\n  Every one of those writes is idempotent — re-running `clearotron start` is safe and nothing needs undoing.\n");
@@ -749,7 +724,7 @@ if (isMain) {
   // be the same silent downgrade refused to build.
   // ── A BOX WITH THE SERVICES INSTALLED HAS ONE CONFIGURATION, AND IT IS NOT THIS ONE ───────────────
   //
-  // Owner ruling,: "whatever is cleanest, simplest and industry-standard expected" —
+  // Ruling,: "whatever is cleanest, simplest and industry-standard expected" —
   // and yes to refusing outright. A box carrying the shipped units is a SERVER: its configuration is the
   // units' `EnvironmentFile` (`%h/.env`), and this command's is `<repo>/.env`, the hand-run laptop file.
   //
@@ -826,7 +801,7 @@ if (isMain) {
   //                        product's own, and the confirmation resolves to a finished report that
   //                        already exists — no engine turn, no register call, no queue entry, no run
   //                        directory. A product the demo carries no report for refuses and names which.
-  //                        (Owner ruling 2026-08-31 14:47, superseding the greyed-control ruling of
+  //                        (Ruling 2026-08-31 14:47, superseding the greyed-control ruling of
   //                        14:44 the same day: "a demo that shows four finished reports and a dead
   //                        button demonstrates the output and hides the thing a buyer is deciding
   //                        about". The greyed control was "a viewer creeping back in".)
@@ -838,11 +813,11 @@ if (isMain) {
   // bound anywhere else in any mode. Sign-in is untouched — the demo signs in like any first start, and
   // the portal mints and prints its passphrase exactly as it does for a real one.
   const DEMO = argv.includes("--demo");
-  // THE DEMO BRINGS ITS OWN ACCOUNT. A fresh install resolves `generic` and nothing else (owner
-  // ruling, 2026-09-08), so the demo account is refused from the roster unless somebody asked for it.
+  // THE DEMO BRINGS ITS OWN ACCOUNT. A fresh install resolves `generic` and nothing else (ruling,
+  // 2026-09-08), so the demo account is refused from the roster unless somebody asked for it.
   // Asked here, once and visibly, rather than at each site that happens to read a roster.
   if (DEMO) process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
-  // ── `--port` MOVES EVERY DOOR IT OPENS (tracker issue 166) ───────────────────────────────────────
+  // ── `--port` MOVES EVERY DOOR IT OPENS ───────────────────────────────────────────────────────────
   //
   // It used to move ONE of the three. `resolvePorts` reads three independent variables with three
   // fixed defaults, and this line set only the portal's — so `demo --port 18860` put the portal on
@@ -865,7 +840,7 @@ if (isMain) {
     Object.assign(ports, moved);
   }
 
-  // ── A BUNDLE OLDER THAN ITS SOURCES IS REBUILT, NOT SERVED (tracker issue 160) ───────────────────
+  // ── A BUNDLE OLDER THAN ITS SOURCES IS REBUILT, NOT SERVED ───────────────────────────────────────
   //
   // Only reachable on a source checkout: `portal-ui/dist` is untracked there, so a `git pull` that
   // changed `portal-ui/src` leaves the bundle behind and every surface still reads healthy. A packaged
@@ -879,45 +854,32 @@ if (isMain) {
 
   // The ADDRESS is not asked for here: a local install has one user, this machine already knows their
   // name, and the address never leaves the machine — `--user` is there for a reader who wants their real
-  // one, and whatever is resolved here is written to `.env` so the question is never put twice. What IS
-  // asked for, and used not to be, is the staff rule the address implies once it is a real one; that is
-  // the block below the address, and `clearotron install` is where the question is actually put.
+  // one, and whatever is resolved here is written to `.env` so the question is never put twice. It is the
+  // first person on the install (`installerGrants`, below); the part of it after the `@` decides nothing
+  // about anybody else.
   let whoami = "user";
   try { whoami = userInfo().username || "user"; } catch { /* a container with no passwd entry */ }
   // In a demo the address is the demo's own and is never written anywhere: see the DEMO block above.
   const user = String(flag("--user", DEMO ? "demo@localhost" : (process.env.PORTAL_LOCAL_USER || `${whoami}@localhost`))).trim().toLowerCase();
   if (!user.includes("@") || user.indexOf("@") !== user.lastIndexOf("@"))
     fatal(`--user "${user}" is not a single email address. It is the one identity that signs in here, and the portal refuses a multi-@ identity outright.`);
-  // ── THE STAFF RULE THIS ADDRESS IMPLIES, STATED BEFORE IT IS WRITTEN ──────────────────────────────
-  //
-  // An explicit `PORTAL_STAFF_DOMAINS` is a decision somebody already made in writing, and it wins
-  // untouched — including a domain the classifier would otherwise refuse, because an operator who
-  // typed it has said what they mean and this command does not overrule that.
-  //
-  // Absent one, the rule is DERIVED from the single address, and that derivation is the defect this
-  // block exists to close. Three outcomes:
+  // ── THE REFUSALS ABOUT THE ADDRESS ITSELF, the wizard's own (shared/staff-domain.mjs) ──────────────
   //
-  //   `localhost` (or any bare hostname)  — one machine, no second person, nothing to ask. Silent, as
-  //                                         it has always been. This is the default path and the only
-  //                                         one a laptop ever reaches.
-  //   a webmail or documentation domain   — refused by `staffDomainFor` itself; there is no yes that
-  //                                         makes it right.
-  //   any other real domain               — refused HERE, with the rule quoted in the words the
-  //                                         settings page uses and the three ways out named.
+  // A public provider or a documentation domain is sent back in the words `clearotron install` uses for
+  // the same address, with where this one came from, because that is the value the reader changes.
   //
   // BEFORE THIS RUN CHANGES THE BOX, deliberately — it sits above the state-written divide further
   // down, with the units gate, the auth-mode gate and the port probe. A refused start has written no
   // `.env`, minted no secret and placed no unit, so the reader's only question — is my install
   // half-made — has one answer.
-  let staffDomains = process.env.PORTAL_STAFF_DOMAINS;
-  if (!staffDomains) {
-    let derived = "";
-    try { derived = staffDomainFor(user); }
-    catch (e) { fatal(e.message); }
-    if (derived && classifyStaffDomain(derived) === "wide")
-      fatal(wideStaffDomainRefusal({ user, domain: derived, envPath: ENV_PATH }));
-    staffDomains = derived;
-  }
+  const refusal = addressRefusal(user);
+  if (refusal) fatal(`${refusal}\n  This address came from ${flag("--user") ? "--user" : `PORTAL_LOCAL_USER, in the environment or ${ENV_PATH}`}.`);
+  // YOUR ORGANISATION'S NAME, which `clearotron install` asks for directly after the address and writes
+  // as CLEAROTRON_ORGANISATION_NAME. It is read only to file the first organisation into a grants file
+  // that holds none (`installerGrants`); after that the grants file is where the name lives, and renaming
+  // it is an edit there. A DEMO TAKES NONE FROM THE SETTING, for the reason it takes no address from it:
+  // the reader's real install must not decide what the demo shows.
+  const organisation = String(flag("--organisation", DEMO ? "" : (process.env.CLEAROTRON_ORGANISATION_NAME ?? "")) ?? "").trim();
 
   say("");
   say(`  ${BRAND.name} ${BRAND.product.toLowerCase()} — local install`);
@@ -958,9 +920,9 @@ if (isMain) {
   // down, which is what the paragraph above says this check is for.
   // The file to send the reader to, MEASURED rather than composed — `envFileRead()` reports what
   // shared/env-local.mjs actually did in this process, and answers null when it read nothing. Its own
-  // header carries the reasoning (tracker issue 200).
+  // header carries the reasoning.
   const portFile = envFileRead();
-  // Set when the probe met OUR OWN client door on its own port (tracker issue 228). Carried out of this
+  // Set when the probe met OUR OWN client door on its own port. Carried out of this
   // loop because both paths below have to act on it: the background path must RESTART the door it
   // adopted, and the foreground path must not spawn a second one beside it.
   let adoptedClientDoor = false;
@@ -987,7 +949,7 @@ if (isMain) {
     // The narrow carve above already proved every installed unit is ours.
     if (backgroundRefresh) break;
     const code = await probe(port);
-    // ── OUR OWN DOOR IS NOT A COLLISION (tracker issue 228) ──────────────────
+    // ── OUR OWN DOOR IS NOT A COLLISION ──────────────────────────────────────
     //
     // `stop` leaves this door up on purpose and says so; refusing here made `stop`'s own "plain
     // `clearotron start` works in a terminal from here" a lie, and left `clearotron demo` unrunnable on
@@ -1006,7 +968,7 @@ if (isMain) {
     // on a privileged port and from an address this host does not have, and names the way out of each;
     // the launcher having its own shorter sentence for one of the three would mean a user meets two
     // different answers to the same question depending on which door refused first.
-    // ── A PORT NOBODY CHOSE IS MOVED RATHER THAN REFUSED (owner ruling, 2026-09-09) ─────────────
+    // ── A PORT NOBODY CHOSE IS MOVED RATHER THAN REFUSED (ruling, 2026-09-09) ─────────────
     //
     // Three conditions, and each is a different reason:
     //   · the address is genuinely taken — anything else is not this case;
@@ -1092,13 +1054,60 @@ if (isMain) {
   for (const d of [paths.pool, paths.workspace, paths.queue, paths.outbox, paths.locks, paths.recipes]) {
     try { mkdirSync(d, { recursive: true }); } catch (e) { fatal(`could not create ${d} (${String(e?.message ?? e)}).`); }
   }
-  if (!existsSync(paths.grants)) {
-    // An empty roster is the correct starting state: it admits the staff domain above and grants no
-    // client anything. What is not legitimate is having no file — the portal refuses to start without
-    // one, because with no grants file every admitted identity resolves to every account.
-    try { writeFileSync(paths.grants, `${JSON.stringify({ tenants: {} }, null, 2)}\n`); }
-    catch (e) { fatal(`could not create the grants file at ${paths.grants} (${String(e?.message ?? e)}).`); }
-    say(`  created        ${paths.grants} (an empty roster — one staff address, no clients yet)`);
+  // ── THE GRANTS FILE, AND THE PERSON WHO INSTALLED IN IT ─────────────────────────────────────────────
+  //
+  // Having no file is not legitimate — the portal refuses to start without one, because with no grants
+  // file every admitted identity resolves to every account. `installerGrants` holds the policy for what
+  // goes in it; this block reads, writes and says what happened.
+  //
+  // READ AND CHECKED FIRST, with the portal's own shape check: a file the portal will refuse is named
+  // here, where the reader can still fix it, rather than as a child that exits after the doors are up.
+  //
+  // A DEMO WRITES ONLY ITS OWN FILE. The demo visitor is simply the first person on a box holding only
+  // demo data, so it gets the installer's entry — in the demo's base and nowhere else. An environment
+  // pointing CLEAROTRON_ACCESS_FILE elsewhere names a real install's roster, and a demo identity with
+  // access to everything does not belong in it.
+  {
+    let existing = null;
+    if (existsSync(paths.grants)) {
+      try {
+        existing = JSON.parse(readFileSync(paths.grants, "utf8"));
+        assertGrantsShape(existing, paths.grants);
+      } catch (e) {
+        fatal(`the grants file at ${paths.grants} cannot be used: ${String(e?.message ?? e)}\n`
+          + "  The portal refuses to start on it as well. Fix that entry by hand, or set CLEAROTRON_ACCESS_FILE to the file you mean.");
+      }
+    }
+    if (DEMO && paths.grants !== installPaths(paths.base).grants) {
+      err(`  WARNING: CLEAROTRON_ACCESS_FILE points this demo at ${paths.grants}, outside ${paths.base}. The demo `
+        + `writes nothing there, so ${user} has no access unless that file already gives it some`
+        + `${existing ? "" : " — and it does not exist, so the portal will refuse to start"}. `
+        + "Unset CLEAROTRON_ACCESS_FILE to run the demo on its own file.");
+    } else {
+      let seeded;
+      try { seeded = installerGrants(existing, { user, organisation }); }
+      catch (e) { fatal(`could not add ${user} to the grants file at ${paths.grants} (${String(e?.message ?? e)}).`); }
+      if (!existing || seeded.changed.length) {
+        // ATOMIC, because a --background refresh runs beside units that read this file per request, and a
+        // reader catching half of it gets malformed JSON.
+        const { atomicWrite } = await import("../driver/progress.mjs");
+        try { atomicWrite(paths.grants, `${JSON.stringify(seeded.grants, null, 2)}\n`); }
+        catch (e) { fatal(`could not write the grants file at ${paths.grants} (${String(e?.message ?? e)}).`); }
+      }
+      if (!existing) say(`  created        ${paths.grants} — ${user}: Run, Manage, access to everything`);
+      else if (seeded.changed.includes("person"))
+        say(`  grants         ${paths.grants} named nobody, so ${user} was added: Run, Manage, access to everything`);
+      if (seeded.changed.includes("organisation")) say(`                 organisation "${organisation}", filed there — rename it there too`);
+      else if (seeded.changed.includes("person") && !Object.keys(seeded.grants.tenants ?? {}).length)
+        say(`                 no organisation named yet — \`${invocationPrefix()}clearotron start --organisation "<name>"\` files the first one`);
+      // REPORTED, NOT REPAIRED. A file that names other people is somebody's decision, and adding this
+      // address to it would give access to everything to an address nobody enrolled.
+      if (seeded.unadmitted)
+        err(`  WARNING: ${paths.grants} gives ${user} no access, so it signs in and every page refuses it.\n`
+          + "  The file already names other people, so this command leaves it as it is. Add under \"people\":\n"
+          + `    "${user}": { "run": true, "manage": true, "everything": true }\n`
+          + "  or start with --user set to an address that file gives access.");
+    }
   }
   // THE REVOCATION LIST, CREATED — not merely named (found in review).
   //
@@ -1165,7 +1174,7 @@ if (isMain) {
   // ONE sample ships today (a multi-country focus search). Three of the four products have no finished
   // run anywhere to freeze — see — so this seeds what exists and picks the rest up unchanged when
   // they are captured.
-  // ── F23 — A REAL INSTALL STARTS EMPTY (OWNER RULING, 2026-09-04) ────────
+  // ── F23 — A REAL INSTALL STARTS EMPTY (RULING, 2026-09-04) ────────
   //
   // Owner, in session, on his first real start: "critical, it started and I still see a demo report in
   // the actual product. Should not be there — should ONLY be in demo. Proper product should have no
@@ -1197,7 +1206,7 @@ if (isMain) {
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
     const { publishSource } = await import("../driver/demo-container.mjs");
     const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
-    // WHAT WAS ALREADY THERE IS SAID TOO (tracker issue 277). This branch used to run only when the pool
+    // WHAT WAS ALREADY THERE IS SAID TOO. This branch used to run only when the pool
     // was empty; it now tops a stale pool up to the package's set, so "seeded 1" on an upgrade is a fact
     // about what was MISSING and says nothing on its own about how many are now listed.
     if (seed.already?.length) {
@@ -1252,7 +1261,7 @@ if (isMain) {
   // process's resolved environment, which is where `<repo>/.env` has already been applied, so a
   // decision recorded in that file survives a start rather than being silently overwritten with "1".
   const declaredFence = String(process.env.CLIENT_MCP_ACCOUNT_ACCESS ?? "").trim();
-  const envs = childEnv({ ports, paths, user, staffDomains, portalSecret, tokenSecret, opsToken,
+  const envs = childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken,
     localWorker: wantWorker, demo: DEMO, clientFence: declaredFence || null });
 
   // ── 3b. the configuration snapshot, so the portal can name this install's MODE ────────────────────
@@ -1300,8 +1309,8 @@ if (isMain) {
   // the processes and thats it its done". The foreground supervisor dies with the terminal — his portal
   // was gone between two of his own sessions and every screen spun. The honest fix on a machine with
   // systemd is not a detach flag and a pid file; it is the same user units a server runs, installed for
-  // exactly the pinned BACKGROUND_UNITS set (the census arm keeps that pin honest). Since tracker issue
-  // 2148 settled point 2 that set INCLUDES the client door, which is why the block below writes the
+  // exactly the pinned BACKGROUND_UNITS set (the census arm keeps that pin honest). Since the owner
+  // settled point 2 that set INCLUDES the client door, which is why the block below writes the
   // door's settings before any unit is placed.
   //
   // THE UNITS READ %h/.env, NOT THIS PROCESS'S ENV. Everything the foreground supervisor would have
@@ -1310,7 +1319,7 @@ if (isMain) {
   // what makes re-running safe, and the same idempotence sentence the foreground fatal carries applies.
   if (wantBackground) {
     // ONE AUTHOR for this path — `driver/runner.mjs` names the same file in the same words since
-    // tracker issue 216 moved the run-configuration refusal there, and two composers of one path
+    // A later change moved the run-configuration refusal there, and two composers of one path
     // fail quietly: a refusal that sends an operator to edit a file the units do not read.
     const HOME_ENV = unitEnvPath();
     const union = { ...envs.mcp, ...envs.portal, ...(envs.worker ?? {}),
@@ -1402,9 +1411,9 @@ if (isMain) {
       };
       const willRead = { ...already, ...union };
       const miss = missingRequirements(willRead, RUN_TABLES);
-      // ── — WHICH HALF OF `blocking` MAY REFUSE A START (tracker issue 216) ─────
+      // ── — WHICH HALF OF `blocking` MAY REFUSE A START ─────────────────────────
       //
-      // Owner ruling 2026-09-06, in session: "someone can install and select key later so it should
+      // Ruling 2026-09-06, in session: "someone can install and select key later so it should
       // still start." So the register, its credential, the engine and the engine's binary NO LONGER
       // refuse here. They refuse AT ORDER TIME — `driver/runner.mjs`'s intake wall, before a stage
       // dispatches and before anything is spent — and `doctor` and the portal report the box as
@@ -1426,7 +1435,7 @@ if (isMain) {
         // of them, and offered `install` as the route. `install` REFUSES a non-terminal — "this is an
         // interactive wizard and stdin is not a terminal", rc 2 — so the one reader who arrives here by a
         // scripted or hosted install was handed a route they cannot take and no address for the route
-        // they can. Same defect as naming a variable and not the file, one level up (tracker issue 202).
+        // they can. Same defect as naming a variable and not the file, one level up.
         //
         // BOTH FILES, and that is the difference from the port refusals, which say `~/.env` "is NOT read
         // here". They are right: nothing in that file reaches a port decision. Here both are true. The
@@ -1456,7 +1465,7 @@ if (isMain) {
           + `client's first search, which is where this surfaced before: as a failed run and a notice saying `
           + `they had been notified.`);
       }
-      // ── THE BOX STARTS AND SAYS WHAT IT CANNOT DO YET (tracker issue 216) ──
+      // ── THE BOX STARTS AND SAYS WHAT IT CANNOT DO YET ──────────────────────
       //
       // An install that comes up unconfigured must not come up SILENTLY unconfigured — that is the
       // failure one step along from the one being fixed: a reader who is told nothing concludes they are
@@ -1466,13 +1475,13 @@ if (isMain) {
         say(`    the doors and the portal are up, and every run is refused at order time, before`);
         say(`    anything is spent, naming what is missing.`);
         for (const r of miss.atOrder) say(`      ${r.name} — ${r.why}`);
-        // ── THE SAME REMEDY THE REFUSAL USED TO CARRY, AND THE SAME TWO FILES (tracker issue 202) ──
+        // ── THE SAME REMEDY THE REFUSAL USED TO CARRY, AND THE SAME TWO FILES ──────────────────────
         //
         // 202's subject was a refusal on THESE values that named no file, on a product with two of them,
         // and offered `install` — a wizard that refuses a non-terminal, so the one reader who arrives
         // here by a scripted or hosted install was handed a route they cannot take.
         //
-        // tracker issue 216 moved that refusal to order time, so this screen is where these values are
+        // A later change moved that refusal to order time, so this screen is where these values are
         // now named to an operator. The remedy travels with them RATHER THAN BEING DELETED WITH THE
         // REFUSAL — 202's property is about the class ("a message about a value names the file that sets
         // it"), not about which gate happened to print it, and the arms in
@@ -1518,7 +1527,7 @@ if (isMain) {
       say(`      ${ENV_PATH}  — the CLI reads this one when you type a command in a shell.`);
       say(`    Editing one does not change the other. To change what the RUNNING product does, edit the`);
       say(`    first and restart the units.`);
-      // PORTS ARE THE EXCEPTION, and leaving it unsaid is what tracker issue 200 was filed about. The
+      // PORTS ARE THE EXCEPTION, and leaving it unsaid is what that gap was. The
       // sentence above is true — a unit takes its port from the EnvironmentFile like everything else —
       // but THIS command probes for a collision using the value it read from the CLI file, before any
       // unit exists. A reader who has just been told to edit the first file, and whose next run refuses
@@ -1541,7 +1550,7 @@ if (isMain) {
       writeFileSync(join(UNIT_DIR, u), renderUnit(text, { ...process.env, ...union }));
     }
     // STDERR IS CAPTURED, not discarded. `stdio: "ignore"` threw systemd's own explanation away before
-    // anyone could read it, which is half of what tracker issue 121 fixed in `connect` and was never
+    // anyone could read it, which is half of what was fixed in `connect` and was never
     // done here. The two-cause remedy below is right and stays; what was missing was the sentence
     // systemd itself wrote.
     //
@@ -1587,7 +1596,7 @@ if (isMain) {
     //
     // This loop ran uncaught. When systemd declined to enable a unit the whole output was
     // `node:internal/errors:983`, a Node stack trace and a status code — no name for what failed, and no
-    // statement of what had happened to the install (tracker issue 203). It is the worst-placed refusal
+    // statement of what had happened to the install. It is the worst-placed refusal
     // in this command: by here the env file, the data directories, the grants roster and the seeded
     // example are written and every unit file is rendered, so the reader is left not knowing whether
     // they have a half-installed deployment. Every other refusal in this command says whether anything
@@ -1620,7 +1629,7 @@ if (isMain) {
     if (backgroundRefresh) for (const u of unitsToRestartOnRefresh(BACKGROUND_UNITS, unitTypeOf)) {
       try { execFileSync("systemctl", ["--user", "restart", u], { stdio: "ignore" }); } catch { /* health check below reports it */ }
     }
-    // ── AN ADOPTED DOOR IS RESTARTED, OR IT KEEPS RUNNING THE OLD TREE (tracker issue 228) ──────────
+    // ── AN ADOPTED DOOR IS RESTARTED, OR IT KEEPS RUNNING THE OLD TREE ──────────────────────────────
     //
     // `enable --now` is a NO-OP on an already-active unit — the finding `unitsToRestartOnRefresh` exists
     // for, measured on the test box as an unchanged MainPID. So a door this run adopted rather than
@@ -1910,7 +1919,7 @@ if (isMain) {
   // supported state and a useful one; an install that refuses to come up at all because a door could
   // not bind is not. The door's own refusal is loud and carries its remedy — measured and recorded as
   // working — so a reader sees why in its output rather than losing the portal along with it.
-  // ADOPTED, NOT RE-SPAWNED (tracker issue 228). On a box where `stop` left the door unit up, spawning a
+  // ADOPTED, NOT RE-SPAWNED. On a box where `stop` left the door unit up, spawning a
   // second door here would bind-fail against the first and print a refusal about a port the reader's
   // assistant is correctly connected to. The unit IS the door; this path just does not add another.
   const clientDoor = adoptedClientDoor
@@ -1937,7 +1946,7 @@ if (isMain) {
   // is reaped, so it is the same fact without the race. The failure mode being avoided is this
   // finding's own defect relocated into its failure path: a dead door announced as one a client's
   // assistant connects to, which is worse than the silence F26 replaced.
-  // AN ADOPTED DOOR IS RUNNING (tracker issue 228). Without this the banner reported "NOT RUNNING …
+  // AN ADOPTED DOOR IS RUNNING. Without this the banner reported "NOT RUNNING …
   // its output above says why" about a door that is up and serving, and pointed the reader at output
   // that does not exist — the one sentence on this screen a reader would act on, and false.
   const doorRunning = adoptedClientDoor || clientDoor?.child?.exitCode === null;

package/bin/stop.mjs

@@ -27,7 +27,7 @@ import { invoke } from "../shared/invocation.mjs";
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
 const say = (s = "") => console.log(s);
 // ON STDERR, because a refusal that scrolls past in the same stream as the success lines is a
-// refusal a script cannot act on and a reader skims (tracker issue 270).
+// refusal a script cannot act on and a reader skims.
 const err = (s = "") => console.error(s);
 
 const argv = process.argv.slice(2);
@@ -49,7 +49,7 @@ for (const u of BACKGROUND_UNITS) {
   const file = join(UNIT_DIR, u);
   if (!existsSync(file)) continue;
   found++;
-  // ── THE STOP IS VERIFIED, AND THE FILE GOES ONLY IF IT WORKED (tracker issue 270) ────────────────
+  // ── THE STOP IS VERIFIED, AND THE FILE GOES ONLY IF IT WORKED ────────────────────────────────────
   //
   // This was `catch { /* already down */ }` — a COMMENT standing in for a check. The comment guessed why
   // the call failed, the next line deleted the unit file regardless, and the line after that announced

package/bin/update.mjs

@@ -314,7 +314,7 @@ export async function update(argv = process.argv.slice(2)) {
     return installed;
   }
 
-  // ── THE BUNDLE THE PULL COULD NOT UPDATE (tracker issue 160) ─────────────────────────────────────
+  // ── THE BUNDLE THE PULL COULD NOT UPDATE ─────────────────────────────────────────────────────────
   //
   // `portal-ui/dist` is untracked on the public tree, so `git pull` above can never bring it forward.
   // A pull that changed `portal-ui/src` therefore leaves the built bundle behind, and every surface

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "3c2277f7fab7452490c86d19802dd60a886a2b06",
-  "version": "0.2.4"
+  "commit": "3709addd55b282b4c38625c841b86b7486d178b8",
+  "version": "0.3.0-beta.1"
 }